Record the completeness-check gate

[arnelirobles]

A gate that earned its place five times in one day, on the barakoCMS capability migration.

The shape: a test that answers "did we miss one" but cannot say no. Two ways that happens, and both look exactly like a working test.

A list somebody maintains answers "no" by construction, because the list and the thing it describes are updated by the same hand at the same moment or not at all. And a key coarser than the rows collapses them: a check on path, over rows keyed on verb and path, passes when a verb goes missing from a path that still has another.

The five, all on the same migration:

• a test fixture seeding a hand-written list of modules, stale within hours because a module gained a capability that day
• a capability-class list, same shape, which went red on a new module and so half-worked
• a module-instance list, same shape, which stayed green while the thing it checked granted nothing at all, and only a mutation found it
• a route inventory covering 32 of 35 routes while its doc comment claimed all of them
• a coverage test comparing paths while its own rows distinguished verbs

Three of those five were written to replace an earlier list of exactly the same kind, which is why this is worth a section rather than a note in a PR.

The remedy has three parts and the third is the one people skip: derive the set from the running system, key on everything that tells two entries apart, and assert a floor. A reflection query that matches nothing passes silently, exactly like a correct one.

Summary by CodeRabbit

• Documentation
  • Added guidance on designing completeness checks to derive their subject from the running system.
  • Clarified that checks should distinguish entries using all relevant row attributes.
  • Documented common causes of false “no” results and referenced a recurring migration incident.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Team

Run ID: d348ff34-68d8-4085-85cb-3dca4c263e6d

📥 Commits

Reviewing files that changed from the base of the PR and between 60e4730 and eba0429.

📒 Files selected for processing (1)

• DELIVERY.md

Included review availability: Your plan provides up to 1 included review per hour; 0 remain after this review.

---

📝 Walkthrough

Walkthrough

The delivery guidance adds a completeness-check gate. It describes two false-negative failure modes and requires checks to derive their subject from the running system and distinguish each row correctly.

Changes

Completeness Check Gate

Layer / File(s)	Summary
Document completeness-check rules DELIVERY.md	Adds guidance for deriving the checked set from the running system and keying on every field that distinguishes rows. Documents two failure modes and a migration incident with five detections in one day.

Estimated code review effort: 1 (Trivial) | ~2 minutes

Merge Risk: ⚪ Minimal · up to eba04

This update documents stronger completeness-check practices without changing runtime behavior. No merge-readiness risk remains.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly describes the main change: documenting the completeness-check gate and its failure-prevention rules.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0…
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/completeness-check-gate

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}