Markdown is never formatted: script/fmt covers only Go, and no prettier config exists #100

New Issue

2026-08-09T07:04:41+02:00

clawbot commented

2026-08-09 07:04:41 +02:00

From the audit against the canonical REPO_POLICIES.md, verified against main at 61f42e6.

The policy states:

> Use platform-standard formatters: black for Python, prettier for JS/CSS/Markdown/HTML, go fmt for Go. Always use default configuration with two exceptions: four-space indents (except Go), and proseWrap: always for Markdown (hard-wrap at 80 columns).

script/fmt:11 runs gofmt -w over Go files and script/fmt-check:11 runs gofmt -l . — Go only. There is no .prettierrc or .prettierignore in the repo. The markdown demonstrably is not prettier output: README.md prose is hard-wrapped at roughly 66-70 columns (e.g. lines 3-8) where proseWrap: always at prettier's default printWidth: 80 would reflow to ~78; TODO.md maxes at 72.

Practical consequence: markdown formatting is currently whatever each author happened to do, and make check cannot catch drift. The repo also serves HTML templates (internal/templates/*.html) which are likewise unformatted and unchecked.

Stated honestly — partly ambiguous. The same policy scopes the config files narrowly ("Documentation and writing repos (Markdown, HTML, CSS) should also have .prettierrc and .prettierignore") and lists only go.mod, go.sum, .golangci.yml as the Go-repo minimum. So whether a Go repo must carry prettier config is genuinely unclear. That markdown should be prettier-formatted with proseWrap: always is not ambiguous. Filing at low severity; close as wontfix if the narrow reading is intended.

Definition of done

.prettierrc (four-space tabs, proseWrap: always) and .prettierignore added.
.prettierignore must exclude REPO_POLICIES.md — it is currently byte-identical to canonical (sha256 117dde7f148ed3cd693b333312f6345a0a0ee84fadbbe5cca559ca6fed4a1775) and reformatting it would break that property, which is the whole point of vendoring it verbatim. Same for CONVENTIONS.md if it survives #97.
script/fmt and script/fmt-check extended to run prettier over *.md (and decide whether to include the HTML templates — Go template syntax and prettier do not always agree, so verify rather than assume).
The resulting reflow committed as a standalone formatting-only commit, per EXISTING_REPO_CHECKLIST.md: "Formatting diffs can be large and should not be mixed with functional changes."
make check green, and running make fmt twice is idempotent.

Coordination

The reflow touches README.md and TODO.md, both modified by both open PRs. Do last, after #55 and #54 have merged — a repo-wide markdown reflow landing before them would conflict with everything.

From the audit against the canonical `REPO_POLICIES.md`, verified against `main` at `61f42e6`. The policy states: > Use platform-standard formatters: `black` for Python, `prettier` for JS/CSS/Markdown/HTML, `go fmt` for Go. Always use default configuration with two exceptions: four-space indents (except Go), and `proseWrap: always` for Markdown (hard-wrap at 80 columns). `script/fmt:11` runs `gofmt -w` over Go files and `script/fmt-check:11` runs `gofmt -l .` — Go only. There is no `.prettierrc` or `.prettierignore` in the repo. The markdown demonstrably is not prettier output: `README.md` prose is hard-wrapped at roughly 66-70 columns (e.g. lines 3-8) where `proseWrap: always` at prettier's default `printWidth: 80` would reflow to ~78; `TODO.md` maxes at 72. Practical consequence: markdown formatting is currently whatever each author happened to do, and `make check` cannot catch drift. The repo also serves HTML templates (`internal/templates/*.html`) which are likewise unformatted and unchecked. **Stated honestly — partly ambiguous.** The same policy scopes the config files narrowly ("Documentation and writing repos (Markdown, HTML, CSS) should also have `.prettierrc` and `.prettierignore`") and lists only `go.mod`, `go.sum`, `.golangci.yml` as the Go-repo minimum. So whether a **Go** repo must carry prettier config is genuinely unclear. That markdown should be prettier-formatted with `proseWrap: always` is not ambiguous. Filing at low severity; close as wontfix if the narrow reading is intended. ## Definition of done 1. `.prettierrc` (four-space tabs, `proseWrap: always`) and `.prettierignore` added. 2. `.prettierignore` **must** exclude `REPO_POLICIES.md` — it is currently byte-identical to canonical (sha256 `117dde7f148ed3cd693b333312f6345a0a0ee84fadbbe5cca559ca6fed4a1775`) and reformatting it would break that property, which is the whole point of vendoring it verbatim. Same for `CONVENTIONS.md` if it survives #97. 3. `script/fmt` and `script/fmt-check` extended to run prettier over `*.md` (and decide whether to include the HTML templates — Go template syntax and prettier do not always agree, so verify rather than assume). 4. The resulting reflow committed as a **standalone formatting-only commit**, per `EXISTING_REPO_CHECKLIST.md`: "Formatting diffs can be large and should not be mixed with functional changes." 5. `make check` green, and running `make fmt` twice is idempotent. ## Coordination The reflow touches `README.md` and `TODO.md`, both modified by both open PRs. Do **last**, after #55 and #54 have merged — a repo-wide markdown reflow landing before them would conflict with everything.

clawbot added this to the 1.0.0 milestone 2026-08-09 07:04:41 +02:00

clawbot referenced this issue

2026-08-09 16:10:39 +02:00

Tracking: 1.0.0 sequencing and critical path #103

clawbot referenced this issue

2026-08-10 16:14:39 +02:00

TODO.md documents a branch-from-main workflow that no longer matches the `next` branching model #106

Sign in to join this conversation.