Audit: README structure¶
What we check¶
The top-level README.md is a pitch, not a reference manual: what
the project is, who it is for, minimal installation instructions, a
small number of usage examples, and curated links into docs/.
Feature catalogues, CI workflow tables, build internals, architecture
descriptions, and dependency lists belong in docs/,
ARCHITECTURE.md, or AGENTS.md instead.
"Is this a good pitch" is a judgment call, so the automated check enforces measurable proxies:
README.mdis at most 150 lines and at most 1200 words;- if the repository has a
docs/directory, at least one README link points into it (composes with thereadme-absolute-linksaudit, which makes that link absolute).
Repositories without a top-level README.md are reported as N/A.
The judgment half of the policy is enforced at the point where README
bloat is actually created: the documentation-review section of each
repository's pre-push audit file carries the canonical
readme-discipline shared block (see the push-audit audit), which
instructs the reviewer to send new feature documentation to docs/
and to treat README growth as a finding.
This audit exists because our READMEs accreted a bullet per feature
per push -- ryll's reached 558 lines -- burying the pitch that a
human landing on the repository page actually wants, and duplicating
content that docs/ already covers.
Template¶
No template -- move detailed content into docs/ (or
ARCHITECTURE.md / AGENTS.md), keep a short pitch, and link to the
moved content. The move must be a move, not a delete: verify the
detail survives somewhere before trimming the README.
Projects¶
This table is regenerated daily by the consistency audit
workflow from scripts/audit-check.py results; do not edit
it by hand.
Last regenerated: 2026-08-23T06:45:38.740880+00:00
| Project | Status | Issue |
|---|---|---|
| actions | compliant | - |
| agent-python | compliant | - |
| client-python | non-compliant | client-python#353 |
| client-python-k3s | non-compliant | client-python-k3s#22 |
| clingwrap | compliant | - |
| cloudgood | N/A | - |
| development | compliant | - |
| divergulent | compliant | - |
| instar | compliant | - |
| kerbside | compliant | - |
| kerbside-patches | non-compliant | kerbside-patches#1525 |
| library-utilities | compliant | - |
| occystrap | compliant | - |
| private-ci | N/A | - |
| ryll | compliant | - |
| sfui | compliant | - |
| shakenfist | compliant | - |
Details for non-compliant projects:
- client-python (Status): README.md has no link into docs/ despite a docs/ directory existing; add curated links to the detailed documentation
- client-python-k3s (Status): README.md has no link into docs/ despite a docs/ directory existing; add curated links to the detailed documentation
- kerbside-patches (Status): README.md is 435 lines / 3077 words (limits: 150 lines, 1200 words); move detail into docs/ and keep the README a pitch; README.md has no link into docs/ despite a docs/ directory existing; add curated links to the detailed documentation