B-MDU7-shared-markdown-yaml-utils-promote-when-surface-grows
Considered while extracting @sksizer/agent-plugin (D-HRNS-harness-model-and-exporters): should
there be a “markdown basics” package that both markdown-contract and our own code consume?
Decision was NO for now — captured here so the idea isn’t lost.
Why deferred: the genuinely-shareable surface is tiny (a 5-line --- fence-split regex plus a
yaml.parse). The heavier layers already have owners — YAML parse is the yaml package’s job, and
structure/content validation is markdown-contract’s (the substrate). A micro-package would sit
between them with almost nothing durable to hold, and if markdown-contract depended on it we’d
have two markdown libraries in the graph plus cross-repo vendoring for ~25 lines. So agent-plugin
vendors the two frontmatter functions privately (frontmatter.ts). Per S-0001 (co-locate first,
promote when shared).
Promote when: there are ≥3 genuinely-general markdown utilities used by ≥2 independent consumers
(e.g. wikilink parsing, anchor/slug utils, link extraction, readFrontmatter). The right home would
then be a new markdown-contract/primitives entry point (grow the existing substrate, layered like
@sksizer/intersect’s .//segments//fs), NOT a sibling package that markdown-contract
depends on.
Separate, stronger extraction candidate noted in passing: @lib/util/yaml’s PyYAML-byte-compatible
dumper (~500 lines, differential-fuzzed) — a substantial reusable utility, unlike “markdown basics”.
Its consumers are the entity-scaffolding byte contracts; revisit independently.