From c0797ca49b1449e38a5cf88605aa57e83d9009bb Mon Sep 17 00:00:00 2001
From: Kunal Lanjewar <5488221+kunallanjewar@users.noreply.github.com>
Date: Wed, 22 Apr 2026 21:59:01 -0700
Subject: [PATCH] fix(hints): trim implementation-leak wiring from 2 Caveat
 strings (QUEST-144)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The Caveat field on Rule is user-facing documentation surfaced via
rules.Definitions() inspection. Two rules (no-brief-24h and
clear-without-report-detail) had a trailing sentence describing how the
engine normalizes TriggerTool via quest.CanonicalToolName — wiring
detail, not user-actionable guidance.

Trimmed both back to their first-sentence form. Moved the
canonical-mapping rationale into a package-level doc comment above
Definitions() so future rule authors still inherit the context. The
normalization call site in engine.go already carried an equivalent
comment.
---
 internal/hints/rules.go | 10 ++++++++--
 1 file changed, 8 insertions(+), 2 deletions(-)

diff --git a/internal/hints/rules.go b/internal/hints/rules.go
index 3b13b6f..7093115 100644
--- a/internal/hints/rules.go
+++ b/internal/hints/rules.go
@@ -39,6 +39,12 @@ type Rule struct {
 //
 // Rule order here is not semantically meaningful: the Engine keys on
 // Rule.ID after loading DB metadata via Store.LoadRules.
+//
+// Rule TriggerTool values are matched against ev.Tool after both sides
+// pass through quest.CanonicalToolName, so rules authored against the
+// canonical name (e.g. quest_fulfill) also match backward-compat aliases
+// (e.g. quest_clear). Add new aliases in internal/quest/aliases.go; the
+// normalization call site lives in Engine.Evaluate (engine.go).
 func Definitions() []Rule {
 	return []Rule{
 		// 💡 hint (keep) — 6 rules.
@@ -82,7 +88,7 @@ func Definitions() []Rule {
 			TriggerTool:   "quest_fulfill",
 			Trigger:       triggerNoBrief24h,
 			FollowThrough: followQuestBrief,
-			Caveat:        "Era-aware severity: 💡 hint on MCP, ℹ️ fyi on Bash CLI (18.7pp gap in ENTRY-29 calibration). TriggerTool is canonical quest_fulfill; quest_clear alias is handled by quest.CanonicalToolName in the engine.",
+			Caveat:        "Era-aware severity: 💡 hint on MCP, ℹ️ fyi on Bash CLI (18.7pp gap in ENTRY-29 calibration).",
 		},
 
 		// ℹ️ fyi (demote) — 3 rules.
@@ -98,7 +104,7 @@ func Definitions() []Rule {
 			TriggerTool:   "quest_fulfill",
 			Trigger:       triggerClearWithoutReportDetail,
 			FollowThrough: followQuestUpdateOrJournal,
-			Caveat:        "Demoted to fyi; short reports are legitimate for trivial clears. TriggerTool is canonical quest_fulfill; quest_clear alias is handled by quest.CanonicalToolName in the engine.",
+			Caveat:        "Demoted to fyi; short reports are legitimate for trivial clears.",
 		},
 		{
 			ID:            "principle-too-long",