docs: adopt the Hanalyx documentation style guide and CI check - #364
Merged
Conversation
The style guide in the Context Plane is the source of truth for developer docs across every Hanalyx repo. Its three hard rules (no em dashes, no emojis, no AI speak) are gates, not preferences, so they need a check that fails the build rather than a convention people remember. Adds scripts/check-doc-style.py, the shared single-file python3 checker, so the same tool runs identically here and in the Node and mixed repos. Wires a Doc style CI job that scans only Markdown changed against origin/main: the repo carries roughly 350 pre-existing findings, and gating changed files lets the check land now instead of waiting for that backlog to clear. BACKLOG.md and the two new context-plane skill files are cleaned to comply, since the checker scans whole changed files rather than diff hunks. make docs-style runs the same command locally.
![github-advanced-security[bot]](https://avatars.githubusercontent.com/in/57789?s=60&v=4){kind=small}
| EM_DASH = re.compile("—") | ||
| # python3's re has no \p{Extended_Pictographic}; approximate with the common emoji blocks. | ||
| EMOJI = re.compile( | ||
| "[\U0001F000-\U0001FAFF\U00002600-\U000027BF\U00002B00-\U00002BFF" |
This was referenced Jul 26, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adopts the Hanalyx developer documentation style guide as the source of truth for
this repo's developer docs, and installs the shared CI check that enforces its
three hard rules: no em dashes, no emojis, no AI speak.
What lands
scripts/check-doc-style.py, copied verbatim from the shared tool. A single-filepython3 script with no dependencies, so the same checker runs identically in this
Go repo and in the Node and mixed repos.
Doc styleCI job withfetch-depth: 0, runningmake docs-style. Thispipeline has no summary job to depend on, so it is wired as a peer of
docs-consistency, the same way every other required check is.make docs-styleandmake docs-style-allfor local runs.Scope of the doc cleanup
The checker scans whole changed files, not diff hunks, so any file this PR touches
had to be cleared. That is
BACKLOG.md(80 em dashes) and the two newcontext-plane skill files (19). Em dashes were rewritten as periods, commas, or
colons depending on the clause, not substituted mechanically.
BACKLOG.mdalso carries a new Security process entry for the vulnerabilityreporting key defect. That edit is what pulled the file into scope for the
cleanup, so the two travel together.
Backlog left deliberately
make docs-style-allreports 356 findings across 20 files: 350 em dashes,concentrated in
CHANGELOG.md(172),CONTRIBUTING.md(24),VERSIONING_PLAN.md(16), and the guide chapters. Gating on changed files lets the check land now and
drains the backlog as files are touched.
CHANGELOG.mdis the one to watch, sinceevery release edits it.
The remaining 6 findings are a false positive on
harness, which is a technicalnoun here (
kensa-fuzzis a failure-injection harness). Filed against the tool'sowner as a Context Plane bug report; not suppressed in this repo.
Verification
make docs-checkstill passes;ci.ymlparses.