Latent markdownlint debt sits invisible until an unrelated edit makes it blocking #3
Reference in New Issue
Block a user
Delete Branch "%!s()"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Why: The global pre-push hook lints only CHANGED files. A tracked markdown file that already violates the ruleset passes indefinitely as long as nobody touches it — then the first unrelated one-line edit pulls the whole file into lint scope and hard-blocks the push on pre-existing errors the editor did not introduce. This lands cost on an unrelated contributor at an unrelated moment, and the natural response under push pressure is a large reformat commit mixed into a small change, or
--no-verify, which defeats the hook entirely.Hit twice in one session in
oleks/claude-plugin-cicd-insights:skills/cicd-insights/SKILL.mdcarried pre-existing MD060 table-column-style errors. Confirmed pre-existing by stashing the change and re-linting the clean tree. Editing one frontmatter line blocked the push until the whole file was reformatted, producing a 177-line diff for what should have been a 1-line change — which also buries the real edit in review..specify/templates/tasks-template.mdhas two MD013 line-length errors (lines 178, 192) right now. Untouched, so currently harmless; it will block whoever first edits that file.specs/.markdownlint-cli2.jsoncexempts generated spec-kit output underspecs/, but.specify/templates/is NOT covered by that exemption.Evidence: this session's work on
cicd-insightsat commitsf905f55(the forced reformat) andd708e40(current HEAD, where the template errors are still present).Acceptance:
.markdownlint-cli2.jsonc's exemption to.specify/templates/(vendored upstream templates, not hand-authored prose), and/or a periodic full-tree lint in CI so debt surfaces on its own schedule instead of ambushing the next editor..specify/templates/tasks-template.md(lines 178, 192) or exempt the path.Links: commits
f905f55,d708e40in oleks/claude-plugin-cicd-insights.Fixed in
d77e7f7.Scoped the tree first rather than fixing the one file that prompted this. A full-tree lint under the global hook config found all the debt confined to
.specify/— 40+ MD013/MD060 errors acrossmemory/constitution.mdand fourtemplates/*.md. No hand-authored file in the repo was dirty.That made the remedy choice easy:
.specify/is spec-kit-managed scaffolding, the same category the existingspecs/.markdownlint-cli2.jsoncalready exempts, and for the same stated reason — it is template output, not hand-authored prose. Editing the vendored templates to satisfy an 80-column limit would mean drifting from upstream and re-drifting on every refresh, andmemory/constitution.mdis generated from one of those templates.So:
.specify/.markdownlint-cli2.jsonc, mirroring thespecs/rule set, with the incident recorded in the file's own comment so a future reader looking at a clean tree does not delete it as unnecessary.Scope deliberately stays narrow.
README.md,skills/**,commands/**andFACTBOOK-*.mdremain fully linted. Whole tree now reports 22 files, 0 issues.Not addressed here, and deliberately so: the general problem that a changed-files-only hook lets debt accumulate invisibly in any repo. This fix removes the loaded gun in this one. A periodic full-tree lint would be the systemic answer, but that belongs wherever the hooks are owned, not in a plugin repo.