Skip to content

Root Markdown is not covered by any format gate and fails prettier --check #1093

Description

@aram356

Problem

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:

  1. 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).
  2. 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.

Context

Found while reviewing #923.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions