|
| 1 | +# Estate Documentation-Debt Audit — 2026-05-26 |
| 2 | + |
| 3 | +**Scanner:** automated sweep of README + docs/ + CHANGELOG + CONTRIBUTING + CODE_OF_CONDUCT + SECURITY presence across 279 git repos. |
| 4 | +**Date:** 2026-05-26. |
| 5 | + |
| 6 | +**Documentation-debt definition used:** |
| 7 | +- README present? How many lines? |
| 8 | +- `docs/` directory present? How many `.md`/`.adoc`/`.rst` files? Total LoC? |
| 9 | +- Wiki indicator: `wiki/` dir, `.wiki` submodule, or in-repo reference? |
| 10 | +- Project hygiene: CHANGELOG.md, CONTRIBUTING.md, CODE_OF_CONDUCT.md, SECURITY.md? |
| 11 | + |
| 12 | +A repo has a **heavily-developed and well-organised wiki** for the purposes of this audit when it satisfies: `docs/` directory has ≥10 substantive markdown/asciidoc/rst files OR there is a `wiki/` directory/submodule. |
| 13 | + |
| 14 | +### Severity distribution (combined) |
| 15 | + |
| 16 | +| Severity | Count | Meaning | |
| 17 | +|---|---|---| |
| 18 | +| CRITICAL | 5 | no README at all | |
| 19 | +| HIGH | 10 | stub README (<20 lines) | |
| 20 | +| MEDIUM | 16 | README OK but no `docs/` directory | |
| 21 | +| LOW | 123 | thin docs (<10 files in `docs/`) | |
| 22 | +| OK | 124 | heavily-developed docs | |
| 23 | + |
| 24 | +### Heavily-developed wikis (≥10 docs files) — exemplars |
| 25 | + |
| 26 | +These ~50 repos meet the user's "heavily-developed and well-organised wiki" bar: |
| 27 | + |
| 28 | +- `007 ` — 43 files / 11879 LoC |
| 29 | +- `affinescript ` — 91 files / 26832 LoC |
| 30 | +- `affinescript-stdlib-pr ` — 85 files / 25238 LoC |
| 31 | +- `airborne-submarine-squadron ` — 13 files / 1050 LoC |
| 32 | +- `anamnesis ` — 11 files / 13004 LoC |
| 33 | +- `aspasia ` — 10 files / 1040 LoC |
| 34 | +- `betlang ` — 10 files / 2837 LoC |
| 35 | +- `bofig ` — 10 files / 4175 LoC |
| 36 | +- `bofj-kitt ` — 70 files / 4218 LoC |
| 37 | +- `boj-server ` — 89 files / 25917 LoC |
| 38 | +- `burble ` — 94 files / 11625 LoC |
| 39 | +- `cloudguard-cli ` — 15 files / 1852 LoC |
| 40 | +- `cloudguard-server ` — 13 files / 1694 LoC |
| 41 | +- `conative-gating ` — 14 files / 5903 LoC |
| 42 | +- `cookie-rebound ` — 54 files / 2238 LoC |
| 43 | +- `dictask ` — 54 files / 2197 LoC |
| 44 | +- `echidna ` — 75 files / 23198 LoC |
| 45 | +- `echo-types ` — 76 files / 18112 LoC |
| 46 | +- `eclexia ` — 48 files / 18209 LoC |
| 47 | +- `email-octad-experiment ` — 70 files / 5565 LoC |
| 48 | +- `excel-economic-numbers-tool ` — 21 files / 7983 LoC |
| 49 | +- `frayed-knot-toolkit ` — 54 files / 2238 LoC |
| 50 | +- `fraying-model-computational-testbed ` — 54 files / 2238 LoC |
| 51 | +- `game-server-admin ` — 55 files / 2439 LoC |
| 52 | +- `gitbot-fleet ` — 23 files / 3511 LoC |
| 53 | +- `git-scripts ` — 15 files / 1558 LoC |
| 54 | +- `gossamer ` — 61 files / 5382 LoC |
| 55 | +- `gv-clade-index ` — 55 files / 2796 LoC |
| 56 | +- `http-capability-gateway ` — 12 files / 4066 LoC |
| 57 | +- `hybrid-automation-router ` — 56 files / 2396 LoC |
| 58 | +- `hypatia ` — 67 files / 21970 LoC |
| 59 | +- `i-human ` — 10 files / 1040 LoC |
| 60 | +- `intsoc-transactor ` — 13 files / 1413 LoC |
| 61 | +- `januskey ` — 18 files / 6288 LoC |
| 62 | +- `julia-the-viper ` — 20 files / 5151 LoC |
| 63 | +- `kategoria ` — 61 files / 2694 LoC |
| 64 | +- `kategoria-pipeline ` — 54 files / 2238 LoC |
| 65 | +- `krl ` — 56 files / 2498 LoC |
| 66 | +- `laniakea ` — 10 files / 3494 LoC |
| 67 | +- `lcb-website ` — 18 files / 418 LoC |
| 68 | +- `llm-grace ` — 72 files / 4841 LoC |
| 69 | +- `methodologies ` — 54 files / 2238 LoC |
| 70 | +- `mtpc-template-repo ` — 54 files / 2197 LoC |
| 71 | +- `my-lang ` — 36 files / 13747 LoC |
| 72 | +- `natsci-studio ` — 55 files / 2437 LoC |
| 73 | +- `nesy-solver ` — 55 files / 2325 LoC |
| 74 | +- `network-ambulance ` — 12 files / 8678 LoC |
| 75 | +- `nextgen-languages ` — 10 files / 2387 LoC |
| 76 | +- `nextgen-typing ` — 56 files / 2436 LoC |
| 77 | +- `npm-avoidant ` — 70 files / 4218 LoC |
| 78 | +- `oblibeny ` — 32 files / 16455 LoC |
| 79 | +- `ochrance-framework ` — 18 files / 5711 LoC |
| 80 | +- `odds-and-sods-package-manager ` — 31 files / 5668 LoC |
| 81 | +- `paint-type ` — 54 files / 2040 LoC |
| 82 | +- `palimpsest-license ` — 43 files / 18101 LoC |
| 83 | +- `pandoc-a2ml ` — 56 files / 2498 LoC |
| 84 | +- `pandoc-k9 ` — 56 files / 2498 LoC |
| 85 | +- `panic-attack ` — 12 files / 2839 LoC |
| 86 | +- `panll ` — 62 files / 19405 LoC |
| 87 | +- `patch-bridge ` — 57 files / 3279 LoC |
| 88 | +- `php-aegis ` — 12 files / 4293 LoC |
| 89 | +- `proof-burrower ` — 62 files / 4015 LoC |
| 90 | +- `protocol-squisher ` — 17 files / 6886 LoC |
| 91 | +- `proven ` — 12 files / 3258 LoC |
| 92 | +- `proven-servers ` — 16 files / 2316 LoC |
| 93 | +- `rattlescript ` — 55 files / 2261 LoC |
| 94 | +- `repos-monorepo ` — 17 files / 3037 LoC |
| 95 | +- `rsr-template-repo ` — 70 files / 4218 LoC |
| 96 | +- `sanctify-php ` — 19 files / 6548 LoC |
| 97 | +- `session-sentinel ` — 57 files / 3387 LoC |
| 98 | +- `snifs ` — 54 files / 2238 LoC |
| 99 | +- `somethings-fishy ` — 56 files / 2498 LoC |
| 100 | +- `squeakwell ` — 54 files / 2238 LoC |
| 101 | +- `standards ` — 321 files / 22993 LoC |
| 102 | +- `standards-as-port ` — 319 files / 22705 LoC |
| 103 | +- `stapeln ` — 14 files / 2036 LoC |
| 104 | +- `statistease ` — 14 files / 1375 LoC |
| 105 | +- `thejeffparadox ` — 11 files / 1058 LoC |
| 106 | +- `the-nash-equilibrium ` — 80 files / 7398 LoC |
| 107 | +- `tma-mark2 ` — 13 files / 4024 LoC |
| 108 | +- `typed-wasm ` — 59 files / 3405 LoC |
| 109 | +- `typell ` — 16 files / 2478 LoC |
| 110 | +- `valence-shell ` — 50 files / 23689 LoC |
| 111 | +- `vcl-ut ` — 65 files / 6613 LoC |
| 112 | +- `verisimdb ` — 51 files / 29597 LoC |
| 113 | +- `verisimiser ` — 69 files / 4106 LoC |
| 114 | +- `voyage-enterprise-decision-system ` — 13 files / 5339 LoC |
| 115 | +- `vscode-a2ml ` — 59 files / 2733 LoC |
| 116 | +- `vscode-k9 ` — 58 files / 2626 LoC |
| 117 | +- `wokelang ` — 58 files / 20193 LoC |
| 118 | + |
| 119 | +### CRITICAL — no README at all |
| 120 | + |
| 121 | + |
| 122 | +### HIGH — stub README (<20 lines) |
| 123 | + |
| 124 | +- `achievements-lab `(2 lines) |
| 125 | +- `asdf-tool-plugins `(14 lines) |
| 126 | +- `blog-drafts `(17 lines) |
| 127 | +- `flatracoon `(19 lines) |
| 128 | +- `git-reticulator `(12 lines) |
| 129 | +- `ipv6-tools `(17 lines) |
| 130 | +- `manifesto `(15 lines) |
| 131 | +- `my-lang `(8 lines) |
| 132 | +- `sdp-hkdf-deployment `(19 lines) |
| 133 | +- `tropical-resource-typing `(5 lines) |
| 134 | + |
| 135 | +### MEDIUM — good README but no `docs/` directory (55 repos) |
| 136 | + |
| 137 | +These have substantial top-level READMEs (≥20 lines) but no `docs/` directory holding deeper material. Symptom of "README has grown to do the work of docs/". Refactor target: split into README (intro + quickstart only) + `docs/architecture.md`, `docs/usage.md`, etc. |
| 138 | + |
| 139 | +- `a2ml_ex `(README=233 lines) |
| 140 | +- `a2ml_gleam `(README=58 lines) |
| 141 | +- `action-trust-layers `(README=75 lines) |
| 142 | +- `agda-stdlib `(README=71 lines) |
| 143 | +- `ai-cli-lab `(README=171 lines) |
| 144 | +- `anvomidav `(README=84 lines) |
| 145 | +- `cafescripto `(README=105 lines) |
| 146 | +- `claude-integrations `(README=100 lines) |
| 147 | +- `claude-memory `(README=80 lines) |
| 148 | +- `coord-tui `(README=215 lines) |
| 149 | +- `cyo `(README=53 lines) |
| 150 | +- `file `(README=156 lines) |
| 151 | +- `filesoup `(README=386 lines) |
| 152 | +- `format-registrations `(README=129 lines) |
| 153 | +- `groove-browser-harness `(README=139 lines) |
| 154 | +- `HOL `(README=82 lines) |
| 155 | +- `homebrew-tap `(README=72 lines) |
| 156 | +- `humor-ecosystem `(README=64 lines) |
| 157 | +- `hyperpolymath-archive `(README=56 lines) |
| 158 | +- `hyperpolymath.github.io `(README=89 lines) |
| 159 | +- `info `(README=46 lines) |
| 160 | +- `ipv6-site-enforcer `(README=181 lines) |
| 161 | +- `jaffascript `(README=98 lines) |
| 162 | +- `julia-ecosystem `(README=87 lines) |
| 163 | +- `julia-professional-registry `(README=79 lines) |
| 164 | +- `k9_ex `(README=114 lines) |
| 165 | +- `k9_gleam `(README=117 lines) |
| 166 | +- `live-files `(README=81 lines) |
| 167 | +- `lua-filters `(README=128 lines) |
| 168 | +- `lucidscript `(README=100 lines) |
| 169 | +- `maa-framework `(README=122 lines) |
| 170 | +- `me-dialect `(README=287 lines) |
| 171 | +- `nafa-app `(README=236 lines) |
| 172 | +- `network-dashboard `(README=274 lines) |
| 173 | +- `nickel-augmentation `(README=83 lines) |
| 174 | +- `patallm-gallery `(README=204 lines) |
| 175 | +- `polyglot-formalisms-gleam `(README=137 lines) |
| 176 | +- `polysafe-gitfixer `(README=216 lines) |
| 177 | +- `polystack `(README=61 lines) |
| 178 | +- `pseudoscript `(README=98 lines) |
| 179 | +- `qubes-sdp `(README=376 lines) |
| 180 | +- `rescript-ecosystem `(README=42 lines) |
| 181 | +- `robodog-ecm `(README=128 lines) |
| 182 | +- `scripts `(README=232 lines) |
| 183 | +- `social-media-tools `(README=207 lines) |
| 184 | +- `ssg-collection `(README=67 lines) |
| 185 | +- `technical-notes `(README=27 lines) |
| 186 | +- `tentacles-agentic-syllabus `(README=25 lines) |
| 187 | +- `the-metadatastician `(README=87 lines) |
| 188 | +- `tree-sitter-a2ml `(README=136 lines) |
| 189 | +- `tree-sitter-k9 `(README=140 lines) |
| 190 | +- `veridical-simulation-core `(README=173 lines) |
| 191 | +- `vex-tools `(README=83 lines) |
| 192 | +- `wordpress-tools `(README=22 lines) |
| 193 | +- `zotero-tools `(README=26 lines) |
| 194 | + |
| 195 | +### Estate-wide hygiene file coverage |
| 196 | + |
| 197 | +| File | Present | Missing | % | |
| 198 | +|---|---|---|---| |
| 199 | +| CHANGELOG.md | 99 | 180 | 35% | |
| 200 | +| CONTRIBUTING.md | 252 | 27 | 90% | |
| 201 | +| CODE_OF_CONDUCT.md | 234 | 45 | 84% | |
| 202 | +| SECURITY.md | 243 | 36 | 87% | |
| 203 | + |
| 204 | +CONTRIBUTING/CODE_OF_CONDUCT/SECURITY are well covered (likely shipped via the `rsr-template-repo` baseline). **CHANGELOG is the headline gap — 65% of repos have none.** |
| 205 | + |
| 206 | +### Empty `docs/` directories (61 repos) |
| 207 | + |
| 208 | +These have a `docs/` directory but no `.md`/`.adoc`/`.rst` files in it. Either delete the empty dir or seed it with the standard skeleton (architecture, usage, contributing). |
| 209 | + |
| 210 | +### Patterns |
| 211 | + |
| 212 | +1. **Wiki uniformity**: ~50 repos have substantive docs (≥10 files). The pattern they share — index.md, architecture.md, then topic deep-dives — suggests these are the template. Propagating that template to the other ~230 repos would close most of the doc debt with minimal hand-authoring. |
| 213 | +2. **README-as-docs anti-pattern**: 55 repos have README ≥20 lines and zero docs/ — the README has absorbed material that belongs in a docs/ tree, hurting both discoverability (the README is too long to skim) and searchability (deep content isn't indexed under its own URL). |
| 214 | +3. **CHANGELOG gap**: 180 repos have no CHANGELOG. Even semi-automated CHANGELOG generation (e.g. from conventional commits, or `git-cliff`) would close this. |
| 215 | + |
| 216 | +### Recommended next moves |
| 217 | + |
| 218 | +1. **Standards-PR** (separate, follow-up): add `docs-template/` skeleton to `rsr-template-repo` so new repos start with the heavy-docs structure pre-populated. |
| 219 | +2. **CHANGELOG generation**: add a `CHANGELOG.md` skeleton + `git-cliff` config to `governance-reusable.yml` so it's CI-enforced. **180-repo sweep.** |
| 220 | +3. **Per-repo PRs** (this audit): each non-OK repo gets a `docs/tech-debt-2026-05-26.md` summarizing its specific gaps + a small first contribution to its docs tree (the `docs-template/` skeleton). |
| 221 | +4. **GitHub Wikis**: this scan cannot see GitHub-hosted wikis (separate repos). If a repo has a populated GitHub Wiki, the doc-debt classification here may be overstated. Spot-check before fixing. |
| 222 | + |
| 223 | +### Coverage caveat |
| 224 | + |
| 225 | +This scan counted `.md`/`.adoc`/`.rst` files but did not assess quality. A repo with 50 placeholder `# TODO` files would score "OK" here but actually have severe doc debt. The per-repo PRs ask maintainers to validate. |
| 226 | + |
| 227 | +--- |
| 228 | + |
| 229 | +🤖 Generated by Claude Code estate-wide documentation-debt scan (2026-05-26). |
| 230 | +Companion docs: `2026-05-26-estate-proof-debt.md`, `2026-05-26-estate-licence-debt.md`. |
0 commit comments