codebase-health: migrate markdown-H2 config surface to structured file (parity with source-control)

[kyle-sexton]

Problem

codebase-health (.claude/codebase-health.md) is the only other markdown-H2 consumer-config surface
besides source-control (now addressed by #1185). Markdown-H2 config is agent-rewritable prose and
requires a bespoke parse for any non-plugin consumer — the same F2/F3 class #163434 fixed for
source-control.

Ask

Evaluate migrating codebase-health's config to a structured first-class layered file (YAML), same as
toolchain's .claude/ecosystems/<x>.yaml and source-control's new well-known neutral SSOT — IF a
non-plugin consumer reads it. If it is plugin-only, markdown-H2 may be fine (the rule targets
tool-agnostic surfaces, not all config). Confirm the consumer set first.

Related

• Parity with feat(source-control): well-known default path for neutral convention SSOT (F1–F4) #1185 (source-control well-known default path)
• The "structured first-class layered file" end-state: docs/topics/commit-convention-well-known-path/design-resolution.md

[kyle-sexton]

Resolved — no migration needed

Investigation: .claude/codebase-health.md is consumed only by the codebase-health plugin
(grep -rl 'codebase-health\.md' plugins/ returns nothing outside plugins/codebase-health/), and
the plugin does not describe it as tool-agnostic / read by commit-msg hooks, CI, or other agents —
unlike source-control's commit-convention (explicitly "read by commit-msg hooks, CI, other agents").

The F2/F3 fragility #1185 fixed applies specifically to config that non-plugin consumers must
markdown-parse. For a plugin-only surface, markdown-H2 is appropriate — it doubles as human-readable
doc with no non-plugin consumer forced to reimplement the H2 grammar, and no cross-tool severance risk.

The "structured first-class layered file" end-state is warranted only if a second, non-plugin consumer
of codebase-health config ever appears. None does today. Closing; reopen if that changes.