Skip to content

Govreview 2a — the causal clusters stop contradicting their own entries - #281

Merged
Polichinel merged 1 commit into
developmentfrom
docs/govreview-p2a-register-clusters
Sep 2, 2026
Merged

Govreview 2a — the causal clusters stop contradicting their own entries#281
Polichinel merged 1 commit into
developmentfrom
docs/govreview-p2a-register-clusters

Conversation

@Polichinel

Copy link
Copy Markdown
Contributor

Phase 2a of the governance consistency review. 8 findings, 5 of the review's 9 contradictions — all in one document, all one root cause.

The finding

The register's conventions call the cluster list "the single authority" on grouping. Five of twelve clusters listed entries as open whose own headers say RESOLVED:

cluster listed open actually
immutability enforcement C-66 RESOLVED 18 Aug
the freeze as a root cause C-57, C-66 RESOLVED 18 Aug
summarize-estimator coherence C-57 RESOLVED 18 Aug
verification-completeness C-74, C-79, C-80 RESOLVED
unchecked completeness claims C-85, C-77, C-80 RESOLVED
doc↔code topology drift C-86 RESOLVED

C-74 is the damning one. It resolved 2026-07-31 — seventeen days before the clusters' own stated review date of 2026-08-17. The last manual review didn't catch an entry closed a fortnight earlier. Manual review of a self-describing list is not a control.

The preamble committed the failure it warns about

"that list is the single authority and this preamble deliberately does not restate it (it drifted when it did)."

…then restated it in the next clause, listing C-57, C-66, C-74 and C-75 as open. All four resolved.

The copy is deleted, not corrected — correcting it rebuilds the thing that drifted.

Check 14

Holds cluster membership against entry status. Brace convention normalised so the check can stay simple — five different forms were in use across twelve clusters, which is why nothing had ever checked this.

Mutation-tested four ways, all firing. The one that matters: an open entry resolving without its cluster being updated — the real-world case, five times over.

The Source: vocabulary was fiction

Ten permitted values were listed. Six appeared in no entry at all. Six of the most-used real sources weren't in the list. A convention describing a practice nobody followed; it now lists what is used.

validate_docs.sh   PASSED (14 checks)
check_doc_refs.py  PASSED · check_arch_tree.py PASSED
ruff / pytest --cov 100%

🤖 Generated with Claude Code

…ey group

Phase 2a of the governance consistency review — 8 findings, 5 of the review's 9
contradictions, all in one document and all one root cause.

The register's Register Conventions section calls its cluster list "the single
authority" on grouping. Five of its twelve clusters named entries as OPEN whose own
headers say RESOLVED:

  immutability enforcement        C-66
  the freeze as a root cause      C-57, C-66
  summarize-estimator coherence   C-57
  verification-completeness       C-74, C-79, C-80
  unchecked completeness claims   C-85, C-77, C-80
  doc<->code topology drift       C-86

**C-74 is the one that matters.** It resolved on 2026-07-31, seventeen days BEFORE the
clusters' own stated review date of 2026-08-17 — so the last manual cluster review did
not catch an entry that had already been closed for over two weeks. Manual review of a
self-describing list is not a control.

**The preamble committed the failure it warns about, in the same sentence.** It read
"that list is the single authority and this preamble deliberately does not restate it
(it drifted when it did)" — and then restated it in the next clause, listing C-57,
C-66, C-74 and C-75 as open. All four are resolved. The abridged copy is deleted
rather than corrected, because correcting it rebuilds the thing that drifted.

**Check 14** now holds cluster membership against entry status. To let it stay simple,
the brace convention is normalised: `= {open ids; + resolved ids}`, or
`= {all resolved: ids}` when nothing in the cluster is open. Five different brace forms
were in use across twelve clusters, which is why nothing had ever checked this.

Mutation-tested four ways, all firing: a resolved entry moved into an open position; a
fully-resolved cluster losing its marker; **an open entry resolving without its cluster
being updated** — the real-world case, which happened five times; and a register with no
clusters at all.

**The Source vocabulary was fiction.** The conventions listed ten permitted `Source:`
values. Six appeared in no entry at all, while six of the most-used real sources —
`code-review`, `expert-code-review`, `review-base-docs`, `review-diff`,
`expert-method-review`, `tech-debt-cleanup` — were absent from the list. A convention
describing a practice nobody followed. It now lists what is actually used.

Register: 95 entries, 10 open, 85 resolved. Still 0 actionable.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@Polichinel
Polichinel merged commit 004045f into development Sep 2, 2026
11 checks passed
@Polichinel
Polichinel deleted the docs/govreview-p2a-register-clusters branch September 2, 2026 21:19
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant