Plan 185: Expose extended-syntax parsers and the flavor model in pkg/markdown (#409)

* Start plan 185: Expose extended-syntax parsers and the flavor model in pkg/markdown

* Plan 185: expose extended-syntax parsers and flavor model in pkg/markdown

Promotes every custom goldmark parser and the per-flavor Feature support
model into a new public pkg/markdown/flavor sub-package. The MDS034 rule
is reduced to a thin adapter; internal/schema's hand-rolled goldmark
config and the rule's own dual parser both fold into the single
goldmark.New call site in pkg/markdown/flavor/parser.go.

- pkg/markdown/flavor: Flavor and Feature types, the support table,
  Detect(doc *markdown.Document, accept func(Feature) bool) []Finding,
  Finding/HeadingIDExtra shapes, four NewParser*/NewPooledParser*
  constructors, and small rewriter helpers (FindHeadingID,
  IsGitHubAlert, LineCol).
- pkg/markdown/flavor/ext: the five custom extensions
  (Superscript, Subscript, MathBlock, MathInline, Abbreviation) and
  their AST node kinds, moved wholesale from
  internal/rules/markdownflavor/ext.
- internal/convention: Flavor is now a type alias for
  pkg/markdown/flavor.Flavor; constants and ParseFlavor are
  re-exported so internal/config compiles unchanged.
- internal/rules/markdownflavor: Check builds a *markdown.Document
  from *lint.File, calls flavor.Detect, and maps findings to
  diagnostics. Fix retains its byte-range edit pipeline but uses
  flavor.NewPooledParser instead of a private singleton.
- internal/schema/validate_content.go: replaces the local
  goldmark.New(extension.Table) with flavor.NewPooledParserWith.
- internal/integration/rules_test.go: drops the goldmark-frontmatter
  test helper in favour of lint.StripFrontMatter + yamlutil.UnmarshalSafe
  so no goldmark.New remains under internal/.
- Contract test pins the public flavor API shape.
- Docs (markdown-library.md, architecture/index.md, cross-system.md,
  go.md) updated to drop the "CommonMark only" wording and document
  the new sub-package.

Verifies all acceptance criteria: pkg/markdown imports no internal/,
no goldmark.New under internal/ or cmd/, no custom AST node types or
parsers outside pkg/markdown, and MDS034 / schema diagnostics remain
byte-identical (existing tests pass unchanged).

https://claude.ai/code/session_0144ZKUS2Zrg7xBft54qyoti

* Fix broken links to moved ext package and lift FindHeadingID coverage

The pinned-version and source mdsmith-check jobs both failed: three
plan/185 references and one architecture-audit reference still pointed
at the now-empty internal/rules/markdownflavor/ext path. Locally the
references resolved because git mv left an empty directory behind;
CI's fresh checkout sees them as dead links.

- plan/185_public-markdown-flavor-library.md: retarget every
  internal/rules/markdownflavor/ext link at pkg/markdown/flavor/ext
  (the new home).
- docs/development/architecture-audit.md: rewrite the
  "markdownflavor/ext sub-package" finding as resolved by plan/185,
  drop the broken link, and trim to stay under the 300-line cap.
- pkg/markdown/flavor/detect.go: drop the defensive nil-AST guards I
  added in detectBareURLs / detectGitHubAlerts; flavor.Detect already
  short-circuits on doc == nil and the original *lint.File variant
  carried no such check.
- pkg/markdown/flavor/detect_edge_test.go: exercise both branches of
  the public FindHeadingID wrapper so codecov/patch sees full coverage
  on the new helper.

https://claude.ai/code/session_0144ZKUS2Zrg7xBft54qyoti

* Fix duplicate link-ref transformer in newParserInternal

Copilot review caught a real bug: goldmark.New() calls DefaultParser()
which already installs DefaultParagraphTransformers(), so the previous
goldmark.WithParserOptions(parser.WithParagraphTransformers(defaults...))
call appended a second link-reference transformer on top. The reset
closure only touched the appended instance; the one inside the default
parser kept pinning the last parsed document's bytes.

Build the parser explicitly with parser.NewParser (one set of block,
inline, and paragraph parsers including the lrp captured for reset)
and install it via goldmark.WithParser, then let goldmark.New's
extension Extend hooks register the additional block / inline parsers
they need. After this change there is exactly one link-ref transformer
in the resulting parser, and the closure returned to NewPooledParser
callers resets that instance.

https://claude.ai/code/session_0144ZKUS2Zrg7xBft54qyoti

* Pool the dual parser in flavor.Detect; inline onlyAccept

Self-review found two issues from the plan-185 changes:

1. Detect built a fresh goldmark parser per call via NewPooledParser,
   running the full Extend hook chain on every Check. The previous
   singleton in internal/rules/markdownflavor avoided this; the move
   to a stateless public Detect regressed it. Add a sync.Pool inside
   the flavor package that hands each Detect goroutine its own
   parser-with-reset pair, mirroring internal/schema's
   contentParserPool. The pool resets the link-reference transformer
   before Put so idle slots do not pin document bytes.

2. fix.go used a one-line onlyAccept helper that was only ever called
   from one site. Inline the closure literal at the call site and
   drop the helper.

A new BenchmarkDetectReusesPool exercises the dual-parser code path
repeatedly; coverage in pkg/markdown/flavor stays at 100%.

https://claude.ai/code/session_0144ZKUS2Zrg7xBft54qyoti

* Expose NearestBlockAncestor, add byte-identical pin test, fill pyramid

Addresses the two remaining self-review concerns and aligns the
package's tests with the test-pyramid rule that every production
function ships its dedicated unit test by name.

Concern #2 — drop the nearestBlockAncestor duplicate:

- Expose NearestBlockAncestor from pkg/markdown/flavor so external
  rewriters (and the rule adapter) share the helper instead of
  duplicating it. Replace the rule's private copy in fix.go with
  flavor.NearestBlockAncestor.
- Add it to the contract test, the markdown-library stable surface
  list, and a dedicated TestNearestBlockAncestorPublic test.

Concern #3 — byte-identical pin test:

- pkg/markdown/flavor/detect_pin_test.go adds a corpus-driven table
  test (pinCorpus) that maps each input to the exact Finding stream
  (feature + 1-based line + 1-based column, in document order).
  Plan 185 acceptance criterion "Table tests pin this" is now an
  explicit gate; any subtle reorder, drop, or shift in MDS034
  diagnostics will break the test with a side-by-side diff.

Test-pyramid alignment:

- TestNearestBlockAncestor (subtests for the skip-non-block and
  orphan branches) plus TestNearestBlockAncestorPublic for the
  exported wrapper.
- TestIsGitHubAlertPublic exercises both branches of IsGitHubAlert
  (alert blockquote / heading-first-child).
- TestLineColPublic pins the documented 1-based semantics of the
  exported LineCol wrapper.
- TestDualFindings covers the dualFindings helper I extracted from
  Detect in the previous commit, asserting both the keep-filter and
  the still-emits-other-features path.

Coverage in pkg/markdown/flavor stays at 100%; mdsmith check and
golangci-lint are clean.

https://claude.ai/code/session_0144ZKUS2Zrg7xBft54qyoti

* Address recall-mode review findings (14 of 15)

Acts on every concrete finding from the local max-effort review pass
except #5 (linkRefResetter interface duplication), which I'm keeping
local: exposing it from pkg/markdown would surface a goldmark fork
detail on the public surface for less duplication value than it costs.

Bugs

- fix.go (#1): MDS034 Fix was calling flavor.NewPooledParser() per
  invocation — same regression I fixed in flavor.Detect last commit,
  mirrored at the parallel Fix call site. Move the pool to package
  level in flavor and expose a callback API, flavor.WithSharedParser,
  used by both Detect's dualFindings and the rule's
  fixByteRangeFeatures.

- rule.go fixGitHubAlerts (#7): the type assertion
  bq.FirstChild().(*ast.Paragraph) plus lines.At(0) was relying on a
  cross-package contract with flavor.IsGitHubAlert. Re-check the
  shape locally so a future relax of IsGitHubAlert cannot turn the
  walk into a panic.

- fix.go taskCheckBoxEdits (#9): nil-check the
  flavor.NearestBlockAncestor return and the block's Lines() before
  calling At(0).

- detect.go (#11, #15): IsGitHubAlert nil-guards bq and the
  paragraph's Lines.Len(); findHeadingID nil-guards h. Both are
  public-API entry points now.

- rule.go ApplySettings (#12): iterate settings keys in sorted order
  so the error for multiple unknown settings is deterministic across
  Go map randomisation.

Simplifications

- detect.go (#2): drop the taskCheckBoxFinding specialisation; the
  TaskCheckBox case in builtinFindingFor calls inlineExtFinding
  directly.

- detect.go (#3): promote isGitHubAlert / lineCol /
  nearestBlockAncestor to the exported names. The previous private +
  one-line public-wrapper pair was duplication; the lowercase
  versions are now gone.

- detect.go dualFindings (#4): return nil rather than an
  always-allocated empty slice on no findings (CLAUDE.md
  allocation-budget rule).

- parser.go (#6): drop NewParser and NewParserWith — they were
  one-line wrappers around the pooled forms. The public surface is
  now NewPooledParser, NewPooledParserWith, and WithSharedParser.

- contract_test.go (#13): move signature pins to package-scope `var
  _ = ...` declarations so the staticcheck "could omit type" rule
  does not fight the explicit-type contract.

Reuse

- pkg/markdown.Edit + Splice (#8): added an optional `Repl []byte`
  field to Edit; Splice now supports replacement in addition to
  deletion. The rule's bespoke `edit` struct and `applyEdits` are
  gone; fix.go composes a []markdown.Edit and feeds it through
  markdown.Splice. Adjacent-edits-with-Repl behaviour is now pinned
  in pkg/markdown's TestSplice.

- lint.UnmarshalFrontMatter (#14): extracted the StripFrontMatter →
  trim `---\n` delimiters → yamlutil.UnmarshalSafe pipeline into one
  helper in internal/lint/frontmatter.go. internal/integration's
  rules_test.go switched to it, dropping its open-coded copy and the
  goldmark-frontmatter import.

Test pyramid

- Added unit tests for IsGitHubAlert's nil/empty-Lines branches,
  FindHeadingID's nil-heading branch, and TestWithSharedParser for
  the new pool callback. Coverage in pkg/markdown/flavor is 100%.
- TestApplyEditsHandlesAdjacentEdits moved into pkg/markdown's
  TestSplice as a sub-test covering the new Repl behaviour.

All tests pass, golangci-lint clean, mdsmith check clean.

https://claude.ai/code/session_0144ZKUS2Zrg7xBft54qyoti

* Refresh bench comment after pool move

The pool moved from inside Detect to package level in commit 08446eb
(WithSharedParser). Update the bench's docstring to point at the new
home so the next reader does not look in the wrong file.

https://claude.ai/code/session_0144ZKUS2Zrg7xBft54qyoti

* Address second-round recall review (F1, F3, F4, F5, F6)

Second focused review of the previous fix-up commit surfaced seven
findings. Fixing five; F2 (atomic ApplySettings) is pre-existing and
masked by clone-before-apply at every call site, F7 (recover boundary
in WithSharedParser) is hypothetical with no current trigger.

F1 + F4: lint.UnmarshalFrontMatter conflated "no front matter" with
"front matter that decoded into a zero struct". A misspelled key
(dropping a letter from "diagnostics", a schema-mismatched field) or
an empty `---\n---\n` block left fm.Settings == nil && fm.Diagnostics
== nil, so the integration fixture loader silently accepted malformed
bad fixtures.

  - UnmarshalFrontMatter now returns (body, hadFrontMatter, err).
    Callers that want to enforce schema check hadFrontMatter rather
    than inspect v's zero state.
  - integration/rules_test.go's parseFixtureFrontMatter uses the
    new bool. A bad fixture with malformed FM now fails loudly with
    the correct "missing front matter" message.
  - Unit tests in lint/frontmatter_test.go pin all four cases (valid
    block, no block, empty fences, unrecognised keys, decode error).

F3: markdown.Splice's docstring promised "ascending and
non-overlapping" but the implementation enforced neither — a
violating edit list crashed inside body[prev:e.Start] with an opaque
"slice bounds out of range" panic. Added an entry-point precondition
check that panics with a descriptive message naming the offending
edit's index, Start, and End. Three new sub-tests in TestSpliceInvariantViolation
pin the message text so any future change to the check surfaces here.

F5: taskCheckBoxEdits's comment claimed "a malformed AST cannot
panic the fix". Technically true after the nil/empty-Lines guards
landed in commit 08446eb, but the guards do NOT close the
silent-corruption case where NearestBlockAncestor skips an
empty-Lines TextBlock and returns the enclosing ListItem — start+3
then deletes the bullet instead of the checkbox. Documented the
goldmark TextBlock invariant the fix relies on and the failure mode
when a hand-built AST violates it.

F6: fixGitHubAlerts's local (Paragraph, non-empty Lines) re-check was
dead code today and would silently skip a fix if flavor.IsGitHubAlert
ever drifted — the worst failure mode for a fix path (diagnostic
flagged but fix did nothing). Removed the local check; the comment
documents why trusting IsGitHubAlert is the right call and which
test pins the contract.

https://claude.ai/code/session_0144ZKUS2Zrg7xBft54qyoti

* Close the F5 silent-corruption path in taskCheckBoxEdits

The previous round's nil/empty-Lines guards did NOT prevent the
silent-corruption case the F5 finding pointed at: NearestBlockAncestor
SKIPS ancestors with empty Lines() and keeps walking up, so a
TaskCheckBox under a Paragraph-with-empty-Lines under a
ListItem-with-populated-Lines yields block=ListItem and start =
bullet-position, not '['-position. The guards both pass; start+3
deletes three bytes from the wrong block.

Add an explicit `f.Source[start] != '['` check that declines the
edit when the byte at Lines.At(0).Start is not the bracket the
task-list parser's invariant promises, plus a bounds check on
start+3 against len(f.Source) for the truly-short-source case.

Three new red/green tests pin the guard:
- non-bracket start (paragraph with arbitrary Lines)
- nil block ancestor (orphan TaskCheckBox)
- bracket runs past EOF (2-byte source)

https://claude.ai/code/session_0144ZKUS2Zrg7xBft54qyoti

* Address round-3 review: Splice negative-Start, IsGitHubAlert contract pin

Recall agent surfaced three findings after commit 17cca70; one was
the F5 silent-corruption path already closed in commit 131a9f1. The
remaining two land here.

#2: markdown.Splice's precondition check fired for negative-Start
edits via the generic "overlaps previous edit ending at 0" panic. A
producer that subtracts past 0 and emits Start=-1 sent the debugger
chasing a non-existent previous edit. Add a dedicated `Start < 0`
guard that names the actual fault, plus a pin in
TestSpliceInvariantViolation.

#3: fixGitHubAlerts removed the local (Paragraph, non-empty Lines)
re-check and trusts flavor.IsGitHubAlert's contract — but no
behavior test pinned that contract. The four existing fix tests
exercise inputs where IsGitHubAlert returns true via the real
parser; they would not catch a future relaxation of IsGitHubAlert
that returns true for a non-Paragraph first child. Add
TestIsGitHubAlertContractPostcondition: walk a corpus of alert /
non-alert / degenerate blockquotes, and on every IsGitHubAlert==true
case assert FirstChild is *ast.Paragraph with non-empty Lines.

Coverage in pkg/markdown and pkg/markdown/flavor stays at 100%;
mdsmith check and golangci-lint clean.

https://claude.ai/code/session_0144ZKUS2Zrg7xBft54qyoti

* Mark plan/185 done

Every task and acceptance criterion is checked off and the
implementation has passed three rounds of recall review with all
follow-up fixes landed. Flip the status from 🔳 to ✅ and refresh
the PLAN.md catalog.

https://claude.ai/code/session_0144ZKUS2Zrg7xBft54qyoti

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: jeduden

PLAN.md

@@ -111,7 +111,7 @@ footer: |
 | 182 | ✅     | sonnet | [Code block convention rules](plan/182_code-block-conventions.md)                                                                       |
 | 183 | ✅     | sonnet | [Skip DedupeDiagnostics via an audited rule.RepoScoped marker](plan/183_dedupe-diagnostics-repo-scoped-skip.md)                         |
 | 184 | ✅     | opus   | [Automate the cross-tool benchmark on merge to main and publish numbers to the assets branch](plan/184_release-benchmark-automation.md) |
-| 185 | 🔲     |        | [Expose extended-syntax parsers and the flavor model in pkg/markdown](plan/185_public-markdown-flavor-library.md)                       |
+| 185 | ✅     |        | [Expose extended-syntax parsers and the flavor model in pkg/markdown](plan/185_public-markdown-flavor-library.md)                       |
 | 186 | ✅     |        | [Centralize UTF-16 column helpers in internal/mdtext](plan/186_arch-fix-utf16-centralize.md)                                            |
 | 187 | ✅     | opus   | [Neutral-corpus engine lever — shared AST walk and Punkt cost](plan/187_neutral-corpus-engine-lever.md)                                 |
 | 188 | 🔲     | opus   | [Regex-over-source rules — inventory and AST-resident replacements](plan/188_regex-vs-ast-inventory.md)                                 |

docs/development/architecture-audit.md

@@ -244,15 +244,14 @@ graduate.
 
 Sub-package of a rule.
 
-The
-[`markdownflavor/ext` package](../../internal/rules/markdownflavor/ext/)
-is used only within the parent rule
+The `markdownflavor/ext` package is
+used only within the parent rule
 (`fix.go`, `parser.go`, `detect.go`).
-This is fine as an internal split.
-Worth a one-sentence package comment
-explaining why it is separate so
-future readers do not read it as a
-separate rule package.
+Fine as an internal split, but worth
+a package comment explaining why it is
+separate. Resolved by
+[plan/185](../../plan/185_public-markdown-flavor-library.md):
+moved to `pkg/markdown/flavor/ext`.
 
 ## Audit 2026-05-17 (range: 7464d273..b5a6d72)
 

docs/development/architecture/cross-system.md

@@ -29,22 +29,23 @@ the contract. The surface's own spec
 steps) lives where the table's "Spec
 doc" column says.
 
-| Boundary                              | Owner in repo                                        | Spec doc                                                                        | Consumers                                                  |
-| ------------------------------------- | ---------------------------------------------------- | ------------------------------------------------------------------------------- | ---------------------------------------------------------- |
-| LSP wire protocol                     | `internal/lsp`                                       | [CLI reference: `lsp`](../../reference/cli/lsp.md)                              | VS Code extension, other editors                           |
-| CLI flags + exit codes                | `cmd/mdsmith`                                        | [CLI reference](../../reference/cli.md)                                         | shell scripts, CI, git hooks                               |
-| `.mdsmith.yml` schema                 | `internal/config`                                    | [Conventions](../../reference/conventions.md)                                   | every project using mdsmith                                |
-| `.mdsmith/kinds/` directory           | `internal/config`                                    | [Kind files](../../reference/kind-files.md)                                     | every project using mdsmith                                |
-| Generated section markers             | `internal/archetype/gensection`                      | [Generated sections](../../background/concepts/generated-section.md)            | every project's Markdown files                             |
-| Claude plugin manifest (published)    | `editors/claude-code/.claude-plugin/plugin.json`     | [Install: Claude plugin](../../guides/install.md)                               | end users via Claude Code marketplace                      |
-| Claude plugin manifest (contributors) | `editors/claude-code-dev/.claude-plugin/plugin.json` | [editors/claude-code-dev/README.md](../../../editors/claude-code-dev/README.md) | mdsmith contributors                                       |
-| Claude marketplace listing            | `.claude-plugin/marketplace.json`                    | [Install: Claude plugin](../../guides/install.md)                               | Claude Code marketplace                                    |
-| Claude skill definitions              | `.claude/skills/*/SKILL.md`                          | [proto](../../../.claude/skills/proto.md)                                       | Claude Code sessions                                       |
-| npm package shim                      | `npm/mdsmith/`                                       | [Install: npm](../../guides/install.md)                                         | Node users                                                 |
-| PyPI wheel shim                       | `python/`                                            | [Install: PyPI](../../guides/install.md)                                        | Python users                                               |
-| asdf / mise plugin                    | external repos                                       | [Install: asdf / mise](../../guides/install.md)                                 | language-tool users                                        |
-| VS Code `contributes`                 | `editors/vscode/package.json`                        | [VS Code integration](../../guides/editors/vscode.md)                           | the extension host                                         |
-| Public Markdown library               | `pkg/markdown`                                       | [Public Markdown Library](../markdown-library.md)                               | `internal/lint`, `internal/release`, external Go importers |
+| Boundary                              | Owner in repo                                        | Spec doc                                                                        | Consumers                                                                 |
+| ------------------------------------- | ---------------------------------------------------- | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
+| LSP wire protocol                     | `internal/lsp`                                       | [CLI reference: `lsp`](../../reference/cli/lsp.md)                              | VS Code extension, other editors                                          |
+| CLI flags + exit codes                | `cmd/mdsmith`                                        | [CLI reference](../../reference/cli.md)                                         | shell scripts, CI, git hooks                                              |
+| `.mdsmith.yml` schema                 | `internal/config`                                    | [Conventions](../../reference/conventions.md)                                   | every project using mdsmith                                               |
+| `.mdsmith/kinds/` directory           | `internal/config`                                    | [Kind files](../../reference/kind-files.md)                                     | every project using mdsmith                                               |
+| Generated section markers             | `internal/archetype/gensection`                      | [Generated sections](../../background/concepts/generated-section.md)            | every project's Markdown files                                            |
+| Claude plugin manifest (published)    | `editors/claude-code/.claude-plugin/plugin.json`     | [Install: Claude plugin](../../guides/install.md)                               | end users via Claude Code marketplace                                     |
+| Claude plugin manifest (contributors) | `editors/claude-code-dev/.claude-plugin/plugin.json` | [editors/claude-code-dev/README.md](../../../editors/claude-code-dev/README.md) | mdsmith contributors                                                      |
+| Claude marketplace listing            | `.claude-plugin/marketplace.json`                    | [Install: Claude plugin](../../guides/install.md)                               | Claude Code marketplace                                                   |
+| Claude skill definitions              | `.claude/skills/*/SKILL.md`                          | [proto](../../../.claude/skills/proto.md)                                       | Claude Code sessions                                                      |
+| npm package shim                      | `npm/mdsmith/`                                       | [Install: npm](../../guides/install.md)                                         | Node users                                                                |
+| PyPI wheel shim                       | `python/`                                            | [Install: PyPI](../../guides/install.md)                                        | Python users                                                              |
+| asdf / mise plugin                    | external repos                                       | [Install: asdf / mise](../../guides/install.md)                                 | language-tool users                                                       |
+| VS Code `contributes`                 | `editors/vscode/package.json`                        | [VS Code integration](../../guides/editors/vscode.md)                           | the extension host                                                        |
+| Public Markdown library               | `pkg/markdown`                                       | [Public Markdown Library](../markdown-library.md)                               | `internal/lint`, `internal/release`, external Go importers                |
+| Public flavor library                 | `pkg/markdown/flavor`                                | [Public Markdown Library](../markdown-library.md)                               | `internal/rules/markdownflavor`, `internal/schema`, external Go importers |
 
 Treat each surface as a public API.
 mdsmith is at major 0 today, so strict
@@ -166,7 +167,15 @@ doc says how the rule applies to it.
   shape `Parse` returns is a break for
   this surface. `Splice` output is
   byte-exact and pinned by the sync-docs
-  golden corpus. Full policy in
+  golden corpus. The
+  **`pkg/markdown/flavor` sub-package**
+  follows the same policy and ships the
+  extended-syntax parsers (tables,
+  strikethrough, task lists, footnotes,
+  definition lists, heading IDs, plus
+  five custom extensions) and the
+  Flavor / Feature support model.
+  Full policy in
   [Public Markdown Library](../markdown-library.md).
 
 ## Common violations to flag

docs/development/architecture/go.md

@@ -52,9 +52,9 @@ question. The current production set:
 - `internal/lsp` — speak the Language
   Server Protocol; consumes the engine.
 - `pkg/markdown` — the one goldmark
-  parser config and the byte-exact
-  producer. Public; see
-  [Public Markdown Library](../markdown-library.md).
+  parse/produce surface (CommonMark+PI);
+  `pkg/markdown/flavor` adds extensions.
+  Public; see [Public Markdown Library](../markdown-library.md).
 - `internal/mdtext` — walk an
   already-parsed AST (slugging, TOC,
   plain-text). `pkg/markdown` produces

docs/development/architecture/index.md

@@ -97,13 +97,35 @@ cmd/mdsmith              internal/lsp
                          surface; public,
                          imports no
                          internal/ package)
+                        └─> pkg/markdown/flavor
+                            (extended-syntax
+                             parsers, the
+                             Flavor / Feature
+                             support model,
+                             and Detect;
+                             public,
+                             imports no
+                             internal/ package)
+                            └─> pkg/markdown/flavor/ext
+                                (the five
+                                 custom
+                                 extensions)
 ```
 
-`pkg/markdown` sits at the bottom: the
+`pkg/markdown` sits at the bottom. It
+owns the canonical CommonMark + PI
 parse path. `internal/lint` and
-`internal/release` depend on it; it
-depends on nothing in the tree. It is
-also a public cross-system surface — see
+`internal/release` depend on it. It
+depends on nothing in the tree.
+
+The `flavor` sub-package adds the
+extended-syntax parsers. It owns every
+custom goldmark parser in the tree.
+The MDS034 rule and the schema engine
+both build on it.
+
+Both packages are public surfaces.
+For details see
 [cross-system contracts](cross-system.md)
 and [Public Markdown Library](../markdown-library.md).
 

docs/development/markdown-library.md

@@ -75,10 +75,17 @@ that matter:
   extension. The closing `---` is matched only
   at the start of a line. So a `---` row inside
   a YAML block scalar does not end it early.
-- **CommonMark only.** The canonical parser
-  enables no GFM extensions. Tables,
-  strikethrough, and the rest are composed
-  separately by the MDS034 flavor detector.
+- **CommonMark by default, extensions in
+  `pkg/markdown/flavor`.** The canonical parser
+  at `markdown.NewParser` enables no GFM
+  extensions. The `pkg/markdown/flavor`
+  sub-package adds GFM tables, strikethrough,
+  task lists, footnotes, definition lists, the
+  heading-ID attribute parser, and five
+  custom extensions (superscript, subscript,
+  math block, math inline, abbreviations). Use
+  `flavor.NewParser` (or `flavor.NewParserWith`
+  for a subset) to opt in.
 - **Byte-stability contract.** `Splice` output
   is pinned byte-for-byte (see the policy
   below). goldmark gives no such cross-version
@@ -213,12 +220,28 @@ the changelog.
 The stable surface:
 
 - `Parse` and `Document` (its fields).
-- `ParseContext`, `NewParser`.
+- `ParseContext`, `NewParser`, `NewPooledParser`.
 - `StripFrontMatter`, `CountLines`.
 - `Splice` and `Edit` (its fields).
 - `ProcessingInstruction` (its exported fields
   and methods), `KindProcessingInstruction`,
   `NewPIBlockParser`, `PIBlockParserPrioritized`.
+- Sub-package `pkg/markdown/flavor`: the
+  `Flavor` type and constants, the `Feature`
+  type and constants, `AllFeatures`, `Supports`,
+  `ParseFlavor`, the `Finding` and
+  `HeadingIDExtra` shapes, `Detect`, the
+  `NewPooledParser` / `NewPooledParserWith`
+  constructors, the `WithSharedParser` callback
+  for borrowing from the package-shared pool,
+  and the small rewriter helpers
+  (`FindHeadingID`, `IsGitHubAlert`, `LineCol`,
+  `NearestBlockAncestor`).
+- Sub-package `pkg/markdown/flavor/ext`: the
+  five custom extension Extender singletons
+  (`Superscript`, `Subscript`, `MathBlock`,
+  `MathInline`, `Abbreviation`) and their node
+  kinds.
 
 Policy:
 

internal/convention/flavor.go

@@ -1,101 +1,41 @@
-// Package convention owns the convention and flavor data shapes
-// independent of any rule. A convention pairs a Markdown flavor with
-// a table of rule presets; the config loader consults this package
-// at load time so a top-level `convention:` selection becomes a base
-// layer beneath the user's own rule config. Rule packages (notably
+// Package convention owns the convention data shape (a Markdown
+// flavor paired with a table of rule presets) independent of any
+// rule. A convention pairs a Markdown flavor with a table of rule
+// presets; the config loader consults this package at load time so a
+// top-level `convention:` selection becomes a base layer beneath the
+// user's own rule config. Rule packages (notably
 // internal/rules/markdownflavor) consume these data shapes — they do
 // not own them — which keeps internal/config from importing a rule.
+//
+// The Flavor identity itself lives in pkg/markdown/flavor; this
+// package re-exports it via type and constant aliases so existing
+// callers under internal/ keep importing convention.Flavor.
 package convention
 
-// Flavor identifies a target Markdown flavor.
-type Flavor int
+import "github.com/jeduden/mdsmith/pkg/markdown/flavor"
 
-// Flavor constants. The zero value is intentionally invalid so that
-// unparsed settings are caught.
+// Flavor is an alias for pkg/markdown/flavor.Flavor; convention.Flavor
+// and flavor.Flavor name the same underlying type.
+type Flavor = flavor.Flavor
+
+// Flavor constants are re-exported from pkg/markdown/flavor so that
+// existing callers (internal/config, the markdown-flavor rule, the
+// convention table below) keep working with the convention.Flavor*
+// names. Add a new flavor by extending the canonical list in
+// pkg/markdown/flavor and adding one alias here.
 const (
-	flavorInvalid Flavor = iota
-	FlavorCommonMark
-	FlavorGFM
-	FlavorGoldmark
-	// FlavorAny accepts every tracked feature. Useful when the
-	// document is destined for an unknown or permissive renderer and
-	// the user wants to disable flavor reporting without disabling
-	// the rule.
-	FlavorAny
-	// FlavorPandoc is Pandoc's default markdown dialect. Accepts
-	// GFM's four features plus footnotes, definition lists, heading
-	// IDs, superscript, subscript, math block, and inline math;
-	// rejects abbreviations (a non-default Pandoc extension).
-	FlavorPandoc
-	// FlavorPHPExtra is PHP Markdown Extra. Accepts tables,
-	// footnotes, definition lists, heading IDs, and abbreviations;
-	// rejects GFM's task lists, strikethrough, bare-URL autolinks,
-	// and every math / sub/superscript feature.
-	FlavorPHPExtra
-	// FlavorMultiMarkdown extends PHP Markdown Extra with math
-	// block and inline math. Like PHP Extra, rejects GFM task lists,
-	// strikethrough, bare-URL autolinks, and sub/superscript.
-	FlavorMultiMarkdown
-	// FlavorMyST is the MyST flavor used by the Sphinx documentation
-	// toolchain. Accepts tables, strikethrough, footnotes,
-	// definition lists, heading IDs, math block, and inline math;
-	// rejects GFM task lists, bare-URL autolinks, sub/superscript,
-	// and abbreviations.
-	FlavorMyST
+	FlavorCommonMark    = flavor.FlavorCommonMark
+	FlavorGFM           = flavor.FlavorGFM
+	FlavorGoldmark      = flavor.FlavorGoldmark
+	FlavorAny           = flavor.FlavorAny
+	FlavorPandoc        = flavor.FlavorPandoc
+	FlavorPHPExtra      = flavor.FlavorPHPExtra
+	FlavorMultiMarkdown = flavor.FlavorMultiMarkdown
+	FlavorMyST          = flavor.FlavorMyST
 )
 
-// IsValid reports whether f names a recognised flavor. The zero
-// value (reserved for "unparsed/unset") and any out-of-range integer
-// cast to Flavor both return false. Implemented in terms of String
-// so the two stay in lock-step: every recognised flavor has a name,
-// and adding a new constant only requires updating the switch in
-// String.
-func (f Flavor) IsValid() bool { return f.String() != "" }
-
-// String returns the canonical lowercase name of the flavor.
-func (f Flavor) String() string {
-	switch f {
-	case FlavorCommonMark:
-		return "commonmark"
-	case FlavorGFM:
-		return "gfm"
-	case FlavorGoldmark:
-		return "goldmark"
-	case FlavorAny:
-		return "any"
-	case FlavorPandoc:
-		return "pandoc"
-	case FlavorPHPExtra:
-		return "phpextra"
-	case FlavorMultiMarkdown:
-		return "multimarkdown"
-	case FlavorMyST:
-		return "myst"
-	}
-	return ""
-}
-
-// ParseFlavor converts a config string into a Flavor. The match is
-// case-sensitive to reject typos like "GFM" that would otherwise
-// silently validate against the wrong flavor.
+// ParseFlavor delegates to pkg/markdown/flavor.ParseFlavor so callers
+// that already import internal/convention do not need a second import.
 func ParseFlavor(s string) (Flavor, bool) {
-	switch s {
-	case "commonmark":
-		return FlavorCommonMark, true
-	case "gfm":
-		return FlavorGFM, true
-	case "goldmark":
-		return FlavorGoldmark, true
-	case "any":
-		return FlavorAny, true
-	case "pandoc":
-		return FlavorPandoc, true
-	case "phpextra":
-		return FlavorPHPExtra, true
-	case "multimarkdown":
-		return FlavorMultiMarkdown, true
-	case "myst":
-		return FlavorMyST, true
-	}
-	return 0, false
+	return flavor.ParseFlavor(s)
 }