From 298ec06ae0aadaec63b123ea902e70bfd03754c3 Mon Sep 17 00:00:00 2001
From: jochen <jschoubben@novox.be>
Date: Thu, 8 Oct 2026 17:02:30 +0200
Subject: [PATCH] Say held updates wait because a walk failed, in the
 glossary's words

The backlog is held after any failed walk, not only a release, and a check is a pull
request's status; the words said the last release failed its check.
---
 cmd/mesh-controller/plain_words.go      |  6 +++---
 cmd/mesh-controller/plain_words_test.go | 22 +++++++++++++++++++++-
 2 files changed, 24 insertions(+), 4 deletions(-)

diff --git a/cmd/mesh-controller/plain_words.go b/cmd/mesh-controller/plain_words.go
index 9e92bffd..5a2938da 100644
--- a/cmd/mesh-controller/plain_words.go
+++ b/cmd/mesh-controller/plain_words.go
@@ -667,7 +667,7 @@ func moduleNeeds(node string, rs []inventory.ResourceHealth) string {
 // authorised (to-be 46 phases 5 and 6).
 const FromMeshMCPServer = "from the mesh MCP server; this notification cannot do it."
 
-// releaseHeldWords are the plain words of updates held after a release failed its gate: which modules wait,
+// releaseHeldWords are the plain words of updates held after a walk failed: which modules wait,
 // on which machines, and where the operator releases them (ADR 0258: a release is not an acknowledgement, so
 // no notification gives it). Raised with the modules and machines (backlogObservation); the kind's fallback
 // knows neither.
@@ -688,8 +688,8 @@ func releaseHeldWords(modules, machines []string) words {
 	}
 	return words{Headline: headline,
 		Needs: "release them " + FromMeshMCPServer,
-		Explanation: fmt.Sprintf("%s%s wait for a person to release them, because the last release failed its "+
-			"check. They are not delivered until then, and stay held if you leave them.", what, where),
+		Explanation: fmt.Sprintf("%s%s wait for a person to release them, because the last walk failed."+
+			" They are not delivered until then, and stay held if you leave them.", what, where),
 		Resolved: "Resolved: the held updates are released"}
 }
 
diff --git a/cmd/mesh-controller/plain_words_test.go b/cmd/mesh-controller/plain_words_test.go
index 74b19716..c0626897 100644
--- a/cmd/mesh-controller/plain_words_test.go
+++ b/cmd/mesh-controller/plain_words_test.go
@@ -241,10 +241,30 @@ func TestUpdatesHeldNameWhatWaitsAndWhereItIsReleased(t *testing.T) {
 	}
 	plainExample(t, got[0], "Updates of openrazer and sensors wait for your release",
 		"Needs you: release them from the mesh MCP server; this notification cannot do it. Updates of openrazer and "+
-			"sensors on g14 and shanks wait for a person to release them, because the last release failed its check. "+
+			"sensors on g14 and shanks wait for a person to release them, because the last walk failed. "+
 			"They are not delivered until then, and stay held if you leave them.")
 }
 
+// **What held them is said in the glossary's words** (2026-10-08 review): the backlog is held after any
+// walk failed, not a release, and a "check" is a pull request's status. So the words say the walk failed,
+// and never that a release failed or a check did — with the modules and machines named or not.
+func TestUpdatesHeldSayTheWalkFailed(t *testing.T) {
+	for _, w := range []words{
+		releaseHeldWords([]string{"openrazer"}, []string{"g14"}),
+		releaseHeldWords(nil, nil),
+		plainWordings["release-held"](conditions.Observation{Scope: conditions.ScopeMesh, ID: "release"}),
+	} {
+		if !strings.Contains(w.Explanation, "because the last walk failed.") {
+			t.Errorf("does not say the walk failed: %q", w.Explanation)
+		}
+		for _, wrong := range []string{"release failed", "check"} {
+			if strings.Contains(w.Explanation, wrong) {
+				t.Errorf("says %q: %q", wrong, w.Explanation)
+			}
+		}
+	}
+}
+
 // mcpVerb is a need that opens with a verb only the mesh MCP server performs (ADR 0258 §1): release, stop,
 // start, restart, and a restore.
 var mcpVerb = regexp.MustCompile(`^(release|stop|start|restart|restore)\b`)