[Docs] The README design-doc table says Implemented where the documents say otherwise #620

New issue

Closed

opened 2026-07-22 16:21:50 +00:00 by brenno · 1 comment

brenno commented

2026-07-22 16:21:50 +00:00

Owner

Found in the pre-publication documentation review.

Evidence: README.md:149-156 lists six of the nine design documents; PROCESS_IMPROVEMENT.md, VERIFICATION.md and LEXICON_LICENTIENAVRAAG.md are missing. This is exactly the defect docs/README.md:73 already corrected and dated on 2026-07-22 ("this list named seven of the nine documents") — the README was not included in that pass.

The status labels also conflict with the banners inside the documents themselves:

Document	README says	The document says (line 3)
OCIWACHT	Implemented	"ontwerp; deels geleverd" — §15 phase 8c is partial
PENTEST_MIAUW	Implemented	"the module ships, and parts of this document are contradicted by the code"
AI_ASSIST	Implemented	"phases 0-3 shipped, phase 4 unbuilt"
GIT_STORAGE	Implemented (merge open)	"phases 0-6 landed — what remains is verification" (§14: OQ-10 on Windows/Linux)

For Git storage, "merge open" is stale on a different axis than the README suggests: what is open is verification on two platforms, not the merge.

Why this matters now: the design documents are carefully maintained, which is unusual and good. The README flattens that nuance into "Implemented" four times, so the project most honest documentation is contradicted by its most-read page.

Proposal: replace the status column with the first fourteen words of each document own **Status:** line, and complete the table to nine rows. Better still, replace the table with one sentence pointing at docs/README.md#design-notes-design, so only one list can ever go stale.

Found in the pre-publication documentation review. **Evidence:** `README.md:149-156` lists six of the nine design documents; `PROCESS_IMPROVEMENT.md`, `VERIFICATION.md` and `LEXICON_LICENTIENAVRAAG.md` are missing. This is exactly the defect `docs/README.md:73` already corrected and dated on 2026-07-22 ("this list named seven of the nine documents") — the README was not included in that pass. The status labels also conflict with the banners inside the documents themselves: | Document | README says | The document says (line 3) | |---|---|---| | OCIWACHT | **Implemented** | "ontwerp; **deels geleverd**" — §15 phase 8c is partial | | PENTEST_MIAUW | **Implemented** | "the module ships, and **parts of this document are contradicted by the code**" | | AI_ASSIST | **Implemented** | "phases 0-3 shipped, **phase 4 unbuilt**" | | GIT_STORAGE | **Implemented** (merge open) | "phases 0-6 landed — what remains is **verification**" (§14: OQ-10 on Windows/Linux) | For Git storage, "merge open" is stale on a different axis than the README suggests: what is open is verification on two platforms, not the merge. **Why this matters now:** the design documents are carefully maintained, which is unusual and good. The README flattens that nuance into "Implemented" four times, so the project most honest documentation is contradicted by its most-read page. **Proposal:** replace the status column with the first fourteen words of each document own `**Status:**` line, and complete the table to nine rows. Better still, replace the table with one sentence pointing at `docs/README.md#design-notes-design`, so only one list can ever go stale.

brenno added the

docs

label

2026-07-22 16:21:50 +00:00

brenno referenced this issue from a commit

2026-07-22 17:07:09 +00:00

docs(readme): een voorpagina die in tien seconden te lezen is (#582 #590 #591 #611 #619 #620 #621 #635)

brenno referenced this issue from a commit

2026-07-22 17:12:52 +00:00

docs(readme): een voorpagina die in tien seconden te lezen is (#582 #590 #591 #611 #619 #620 #621 #635)

brenno referenced this issue

2026-07-22 17:14:10 +00:00