Small, reproducible formatting defect in devague plan export, found because it turned a downstream repo's markdown lint job red.
What happens
devague plan export writes a plan-md whose list blocks are not surrounded by blank lines, which fails markdownlint's MD032 (blanks-around-lists).
In agentculture/embodiment it surfaced as two violations in the exported plan at commit f6c423f. Confirmed it is the exporter and not a local edit: git show f6c423f:docs/plans/<plan>.md lints red identically, before anything downstream touched it.
The fix on our side is two blank lines — trivial. The reason it is worth filing is that it recurs on every re-export: a repo whose CI runs markdownlint-cli2 "**/*.md" (embodiment's lint job does) goes red every time someone runs devague plan export, and the fix has to be reapplied by hand each time.
Why it bites this workflow particularly
The /spec-to-plan → /assign-to-workforce → /deviate flow re-exports the plan repeatedly — every time a task is added, amended, or a deviation reshapes the graph. Over this one cycle we re-exported perhaps six times. Each export reintroduces the violation, and a hand-fix between exports is exactly the kind of edit that gets lost in the next one.
Suggested fix
Emit a blank line before and after every list block in the plan-md renderer. Worth checking devague export (the spec-md renderer) for the same shape while you are in there — I did not verify whether it has the same issue, since our spec export happened to lint clean.
A golden-file test rendering a plan with adjacent list/heading blocks and asserting the output passes markdownlint would pin it; docs/spec-contract.md's schema contract is presumably the place that already fixes the rendered shape.
Not claimed
That every consumer hits this — only repos that lint markdown in CI and export plans into a linted path. Ours does both, which is why it showed up rather than being invisible.
Measured on devague 0.22.0.
Small, reproducible formatting defect in
devague plan export, found because it turned a downstream repo's markdown lint job red.What happens
devague plan exportwrites a plan-md whose list blocks are not surrounded by blank lines, which failsmarkdownlint's MD032 (blanks-around-lists).In
agentculture/embodimentit surfaced as two violations in the exported plan at commitf6c423f. Confirmed it is the exporter and not a local edit:git show f6c423f:docs/plans/<plan>.mdlints red identically, before anything downstream touched it.The fix on our side is two blank lines — trivial. The reason it is worth filing is that it recurs on every re-export: a repo whose CI runs
markdownlint-cli2 "**/*.md"(embodiment's lint job does) goes red every time someone runsdevague plan export, and the fix has to be reapplied by hand each time.Why it bites this workflow particularly
The
/spec-to-plan→/assign-to-workforce→/deviateflow re-exports the plan repeatedly — every time a task is added, amended, or a deviation reshapes the graph. Over this one cycle we re-exported perhaps six times. Each export reintroduces the violation, and a hand-fix between exports is exactly the kind of edit that gets lost in the next one.Suggested fix
Emit a blank line before and after every list block in the plan-md renderer. Worth checking
devague export(the spec-md renderer) for the same shape while you are in there — I did not verify whether it has the same issue, since our spec export happened to lint clean.A golden-file test rendering a plan with adjacent list/heading blocks and asserting the output passes
markdownlintwould pin it;docs/spec-contract.md's schema contract is presumably the place that already fixes the rendered shape.Not claimed
That every consumer hits this — only repos that lint markdown in CI and export plans into a linted path. Ours does both, which is why it showed up rather than being invisible.
Measured on devague 0.22.0.