From b2462e48a18f031bbcdde0f6af32e99f8779ec1d Mon Sep 17 00:00:00 2001
From: Andreas Trawoeger <aitrawog@gmail.com>
Date: Wed, 28 Oct 2026 20:46:41 +0100
Subject: [PATCH] test(skills): the vacuity guard gets its own red arm
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The control's second half — a body that IS read but whose prose never invokes
the command it documents, so the control compares nothing in it — was asserted
inline, with nothing in the suite exercising its FAILING branch. The suite's
other red arm covers the COVERAGE rule; it does not touch this one.

The rule moves into skillDocIsVacuous, so the control calls the function the
test exercises (one implementation), and TestSkillDocVacuityIsEffective gives
it two arms: a body that never invokes the command (the guard must fire) and a
body that does (the guard must stay silent).

This is the one non-blocking observation opencharly/plugin-box#68's validator
review raised, and it is fixed here rather than filed away
(opencharly/plugin-box#69).

Assisted-by: Claude Code minimax/minimax-m3.1-flash:cloud (fully tested and validated)
---
 candy/plugin-box/skill_doc_flags_test.go | 40 +++++++++++++++++++++++-
 1 file changed, 39 insertions(+), 1 deletion(-)

diff --git a/candy/plugin-box/skill_doc_flags_test.go b/candy/plugin-box/skill_doc_flags_test.go
index bb66d5a..1dc8ccd 100644
--- a/candy/plugin-box/skill_doc_flags_test.go
+++ b/candy/plugin-box/skill_doc_flags_test.go
@@ -296,6 +296,14 @@ func flagSectionBullets(body []string) []docClaim {
 	return out
 }
 
+// skillDocIsVacuous reports whether a body makes NO usage claim for the command it documents —
+// the state in which the control compares nothing in that body, so every assertion about it
+// passes by default. The rule lives in a function so that the guard has its own RED ARM: a
+// control that cannot fail is not coverage.
+func skillDocIsVacuous(body []string, command string) bool {
+	return len(usageClaims(body, command)) == 0
+}
+
 // TestSkillBodiesDocumentOnlyRealFlags is the control. Every flag the body offers for its own
 // command must be a flag the command accepts, and every environment variable it pairs with one of
 // its flags must be one of the command's own bindings.
@@ -322,7 +330,7 @@ func TestSkillBodiesDocumentOnlyRealFlags(t *testing.T) {
 			flags, envs := kongSurface(t, tc.grammar)
 
 			claims := usageClaims(body, tc.command)
-			if len(claims) == 0 {
+			if skillDocIsVacuous(body, tc.command) {
 				// A body that never invokes its own command is read by NOTHING here: the usage
 				// claims are what tie a flag in the prose to this command's grammar, and a body
 				// with none of them passes every assertion below without being compared to
@@ -423,3 +431,33 @@ func TestSkillDocCoverageIsEffective(t *testing.T) {
 		t.Fatalf("the coverage check did not report the stale case: %v", stale)
 	}
 }
+
+// TestSkillDocVacuityIsEffective is the VACUITY GUARD's RED ARM: the guard must fire on a body
+// that never invokes the command it documents, and stay silent on a body that does. The guard is
+// what stops a case from passing by comparing nothing, so a guard that cannot fire would leave
+// the control's silence indistinguishable from its agreement.
+func TestSkillDocVacuityIsEffective(t *testing.T) {
+	neverInvokes := []string{
+		"# The command",
+		"",
+		"The command is described in prose, never run.",
+		"",
+		"```",
+		"charly box other --flag",
+		"```",
+	}
+	if !skillDocIsVacuous(neverInvokes, "charly box build") {
+		t.Fatal("the vacuity guard did not fire on a body that never invokes the command it documents")
+	}
+
+	invokes := []string{
+		"# The command",
+		"",
+		"```",
+		"charly box build --flag",
+		"```",
+	}
+	if skillDocIsVacuous(invokes, "charly box build") {
+		t.Fatal("the vacuity guard fired on a body that DOES invoke the command it documents")
+	}
+}