fix(debt): pay Debtfile down to its ceilings (Debt ratchet green)

[hyperpolymath]

Why

The required check governance / Debt ratchet has been red on main since #1061, and it blocks every PR, #1067 included. Two measured counts sat above their ceilings in .machine_readable/Debtfile.a2ml:

entry	before	ceiling	after (measured)
docs-md-not-adoc	2	1	1
gate-scripts-without-tests	45 live (43 committed, stale)	40	40

This PR pays the debt down. No ceiling is changed.

What

• docs/tier3-gate-probe.md → docs/tier3-gate-probe.adoc: same content, with a CC-BY-SA-4.0 header added (the licensing policy's docs licence). Nothing references the file.

  • ⚠ The file describes itself as a one-shot probe ("Delete the branch once read"), so deleting it is also defensible. That is an owner call; conversion was the arm ruled.

• Five new tests. Each gate had never been shown able to fail.

  test	gate	assertions	mutants killed
  uuid-v7-test.sh	check-uuid-v7.sh	11	2/2 (accept any variant · never set status=1)
  mustfile-structure-test.sh	check-mustfile-structure.sh	11	2/2 (no hollow check · no final flush)
  language-guide-test.sh	check-language-guide.sh	13	2/2 (drop "Known gaps" · skip R9)
  shell-test-suite-test.sh	run-shell-test-suite.sh	14	2/2 (no zero-discovery guard · swallow failures)
  descriptile-policy-test.sh	check-descriptile-policy.sh	11	2/2 (drop -e · never set status=1)

  Every mutant was checked with bash -n before its red result was trusted.

• The uuid-v7 and descriptile tests assemble their non-conforming fixtures at runtime. Both gates scan this repository (uuid-v7.yml, and scripts/*.sh as a pathspec matches scripts/tests/), so a literal fixture would turn the real gate red on its own test. I ran both real gates over the branch to confirm this: rc=0.

Verified locally

• check-debtfile-structure.sh: OK (8 entries)
• check-debt-ratchet.sh <base sha bd9313a6>: OK, every ceiling unchanged
• Both probes re-run live: 1 and 40
• All 5 new tests pass: 60 assertions, 0 failures

Findings, filed separately (not fixed here)

• check-uuid-v7.sh has a greedy sed .* that checks only the last UUID on each line. A line reading <v4> <v7> passes (rc=0); <v7> <v4> is caught.
• The gate-scripts-without-tests probe can't see scripts/tests/actions-policy-486-test.sh. That file already exercises check-actions-policy.sh, set-allowed-actions.sh and rsr-selfaudit.sh, so the probe over-counts untested scripts by up to 3.

Unblocks #1067.

🤖 Generated with Claude Code

https://claude.ai/code/session_01WPSJ7fBhVAMcpSffCBWUDo

[coderabbitai]

Warning

Review limit reached

Next included review available in 21 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used the included review currently available.

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Learn how review limits work.

Review configuration:

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Advanced

Run ID: 50c53156-6fd2-42d8-b570-37da2bde5149

📥 Commits

Reviewing files that changed from the base of the PR and between bd9313a and 036970b.

📒 Files selected for processing (8)

• .machine_readable/Debtfile.a2ml
• docs/tier3-gate-probe.adoc
• docs/tier3-gate-probe.md
• scripts/tests/descriptile-policy-test.sh
• scripts/tests/language-guide-test.sh
• scripts/tests/mustfile-structure-test.sh
• scripts/tests/shell-test-suite-test.sh
• scripts/tests/uuid-v7-test.sh

---

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.}