You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Root-level Markdown (CLAUDE.md / AGENTS.md, README.md, CONTRIBUTING.md, SEQUENCE.md, …) is not covered by any formatting gate, and the agent guide
currently fails prettier --check.
The format-docs CI job runs npm run format from docs/, which is prettier --check . — scoped to the docs/ directory. Root files are never
inspected. Verified on current main:
$ cd docs && npx prettier --check ../CLAUDE.md
[warn] ../CLAUDE.md
[warn] Code style issues found in the above file.
The drift is cosmetic — misaligned Markdown table padding in the
"Configuration Files" and "Key Files" tables, about 38 lines total. No content
is wrong.
Why file it
This is pre-existing on main, not introduced by any open PR. It is worth
recording because the gap is easy to misread: a PR that edits the agent guide
can show a green format-docs check while the file it changed was never
checked. That makes "docs format passes" misleading evidence in a test plan.
Proposed fix
Either:
Extend the gate — add a root-level prettier check covering *.md at the
repo root, then run --write once to normalize the existing drift. Note
this will touch the agent guide, so it is best landed when no large doc PR
is in flight (see Make AGENTS.md the source of truth with CLAUDE.md as a symlink #923).
Or explicitly exclude root Markdown via .prettierignore and document
that root docs are hand-formatted, so the absence of a gate is intentional
rather than accidental.
Option 1 is preferable — the table drift is exactly the kind of thing a
formatter should own.
Problem
Root-level Markdown (
CLAUDE.md/AGENTS.md,README.md,CONTRIBUTING.md,SEQUENCE.md, …) is not covered by any formatting gate, and the agent guidecurrently fails
prettier --check.The
format-docsCI job runsnpm run formatfromdocs/, which isprettier --check .— scoped to thedocs/directory. Root files are neverinspected. Verified on current
main:The drift is cosmetic — misaligned Markdown table padding in the
"Configuration Files" and "Key Files" tables, about 38 lines total. No content
is wrong.
Why file it
This is pre-existing on
main, not introduced by any open PR. It is worthrecording because the gap is easy to misread: a PR that edits the agent guide
can show a green
format-docscheck while the file it changed was neverchecked. That makes "docs format passes" misleading evidence in a test plan.
Proposed fix
Either:
*.mdat therepo root, then run
--writeonce to normalize the existing drift. Notethis will touch the agent guide, so it is best landed when no large doc PR
is in flight (see Make AGENTS.md the source of truth with CLAUDE.md as a symlink #923).
.prettierignoreand documentthat root docs are hand-formatted, so the absence of a gate is intentional
rather than accidental.
Option 1 is preferable — the table drift is exactly the kind of thing a
formatter should own.
Context
Found while reviewing #923.