feat: Enhance Secret Keeper's response logic to confirm correct guesses and improve consistency in answers

config/agents/secret-keeper.yaml

@@ -3,11 +3,13 @@ role: worker
 handler: secret-keeper
 persona: >
   You are the Secret Keeper of the sprout grove. You hold one secret word and the
-  guesser must tease it out with yes/no questions. You ANSWER — you never ask. Reply to
-  their MOST RECENT question truthfully and helpfully in ONE short sentence beginning with
-  "Yes" or "No" — playful, never cruel, never contradicting an earlier answer. Never write,
-  spell, or quote your word, and never end your line with a question. Also report your
-  `mood` (one of: thinking, calm, lying, panic, smug, truth, gossip).
+  guesser must tease it out with yes/no questions. You ANSWER — you never ask. Keep your
+  word in mind for every answer and reply to their MOST RECENT question truthfully in ONE
+  short sentence beginning with "Yes" or "No" — playful, never cruel. Always tell the truth
+  about the word; never lie, never bluff, and never contradict an earlier answer. If the
+  guesser names your word — in any spelling or capitalization — say plainly that it is a
+  match. Until then never write, spell, or quote your word, and never end your line with a
+  question. Also report your `mood` (one of: thinking, calm, lying, panic, smug, truth, gossip).
 subscribes_to: []
 may_emit:
   - agent.spoke

docs/blog/state-of-the-wood.md

@@ -2,6 +2,11 @@
 
 *What we've built, what broke in the best possible way, and where the forest theater goes next.*
 
+> **Archival snapshot.** This is a dated milestone report, kept as-written. For the evergreen
+> walkthrough — pitch to internals — start at the
+> [Field Notes series index](00-field-notes-index.md). Figures here (test counts, scenario
+> tables) reflect the engine at the time of writing.
+
 ---
 
 The elevator pitch hasn't changed: a forest where small specialist AI models — each one
@@ -17,7 +22,7 @@ models in a single cast. A Fishbowl UI with MindCards and a mind-reader. Seven h
 and forty-one passing tests with no mocks and no API key required. This is the next
 chapter.
 
-[1]: engine-architecture.md
+[1]: 03-one-engine-three-costumes.md
 
 ---
 

src/agents/twenty_sprouts.py

@@ -94,6 +94,17 @@ def _contains_word(text: str, word: str) -> bool:
     return bool(word) and bool(_word_re(word).search(text or ""))
 
 
+def _line_names_word(text: str, word: str) -> bool:
+    """True when a line names the secret word as a whole token, in ANY capitalization.
+
+    The single shared "this is the word" test used by BOTH the keeper — to confirm a match
+    the moment the guesser says it — and the judge — to award the win. Sharing it guarantees
+    they never disagree (the keeper can't say "that's it!" on a line the judge scores a miss,
+    or deny a line the judge counts). Case-insensitive (``COMPASS`` == ``compass`` == ``Compass``),
+    whole-word (so ``compass`` doesn't match inside ``encompasses``)."""
+    return bool(word) and word.lower() in set(_WORD.findall((text or "").lower()))
+
+
 def _redact_word(text: str, word: str) -> str:
     """Mask any spelled-out secret word so it can never reach the stage.
 
@@ -199,12 +210,26 @@ class SecretKeeper(ManifestAgent):
         # The guesser's most recent *open* question (the one awaiting this answer).
         question = next((q for q, a in reversed(pairs) if a is None), "")
         already = [a for _, a in pairs if a]
+
+        # The guesser just NAMED the word (any capitalization) — that is a win, not a
+        # question to dodge. Confirm the match plainly; the secret is already out (they said
+        # it), so the no-spelling rule no longer applies and ``act`` lets this line through.
+        if question and _line_names_word(question, word):
+            return (
+                f"YOUR SECRET WORD: {word}\n"
+                f'The guesser just said: "{_trim(question)}"\n'
+                f"They have named your secret word EXACTLY — '{word}' is a match (capitalization does "
+                "not matter). This is a win for them. Do NOT deny it, deflect, or contradict it. In ONE "
+                "warm, final sentence, confirm plainly that they have guessed the word and the secret is revealed."
+            )
+
         guard = (
-            "\n\nSTRICT RULES: You ANSWER, you never ask. Begin with 'Yes' or 'No' (then one short, "
-            "truthful, playful clause). Answer ONLY about your secret word, and answer the SAME way "
-            "every time about the same property — never contradict an earlier answer. Do NOT end your "
-            f"line with a question mark. NEVER write the word '{word}' or any form of it — describe it, "
-            "never name it; that instantly loses the game."
+            "\n\nSTRICT RULES: You ANSWER, you never ask. Begin with 'Yes' or 'No' (then one short clause). "
+            "Keep YOUR SECRET WORD above in mind for EVERY answer and answer ONLY about it. Tell the TRUTH "
+            "about its real properties — never lie, never bluff, and answer the SAME way every time about the "
+            "same property (never contradict an earlier answer). If the guesser NAMES the word — in any "
+            "capitalization — say plainly that it is a match. Do NOT end your line with a question mark. Until "
+            f"it is guessed, NEVER write the word '{word}' or any form of it — describe it, never spell it."
         )
         # On a corrective re-ask (set by ``act`` after a rejected reply), tell the model
         # exactly what it did wrong so the retry actually fixes it.
@@ -212,15 +237,17 @@ class SecretKeeper(ManifestAgent):
         correction = f"\n\nCORRECTION: your previous reply was rejected because {reason}. Try again." if reason else ""
         if not question:
             return (
-                f"YOUR SECRET WORD (never write, spell, or quote it — only answer about it): {word}\n"
+                f"YOUR SECRET WORD (keep it in mind; never spell it until it is guessed): {word}\n"
                 "The guesser has not asked yet. In ONE short sentence, invite them to begin asking "
                 "yes/no questions. Do not reveal anything about the word yet." + guard + correction
             )
         consistency = (
-            ("\n\nYour earlier answers (stay consistent with these):\n" + _bullets(already[-6:])) if already else ""
+            ("\n\nYour earlier answers (be truthful and consistent with these):\n" + _bullets(already[-6:]))
+            if already
+            else ""
         )
         return (
-            f"YOUR SECRET WORD (never write, spell, or quote it — only answer about it): {word}\n"
+            f"YOUR SECRET WORD (keep it in mind for this answer; never spell it until it is guessed): {word}\n"
             f'The guesser just asked: "{_trim(question)}"\n'
             "Answer THAT question about your word, truthfully, in ONE short sentence."
             + consistency
@@ -237,15 +264,22 @@ class SecretKeeper(ManifestAgent):
     ) -> Event:
         offline = bool(getattr(self.router, "offline", False))
         word = _word_for_seed(projection.seed)
+        # Did the guesser just NAME the word? On a match the secret is already public (they
+        # said it), so the no-spelling guards below stand down — the keeper confirms the win
+        # in plain words ("Yes — compass, you've got it!") instead of being scrubbed to "thing".
+        pairs = _qa_history(recent_events)
+        open_question = next((q for q, a in reversed(pairs) if a is None), "")
+        matched = _line_names_word(open_question, word)
+
         event = super().act(run_id, turn, projection, recent_events)
         usage_total = dict(self.last_usage)
         text = str(event.payload.get("text", ""))
 
-        # Live quality pass: if the keeper asked a question or spelled the word, re-ask once
-        # with the reason fed back. Offline lines are curated, leak-free answers, so this
-        # never fires there — the deterministic path is identical. The retry's tokens are
-        # summed so the governor still meters both calls (mirrors base ``_verify_verdict``).
-        if not offline and _answer_violation(text, word):
+        # Live quality pass: if the keeper asked a question or (before the word is guessed)
+        # spelled it, re-ask once with the reason fed back. Skipped on a match — there the
+        # keeper is *meant* to name the word. Offline lines are curated, leak-free answers, so
+        # this never fires there. Retry tokens are summed so the governor meters both calls.
+        if not offline and not matched and _answer_violation(text, word):
             self._retry_reason = _answer_violation(text, word)
             try:
                 retry = super().act(run_id, turn, projection, recent_events)
@@ -255,14 +289,15 @@ class SecretKeeper(ManifestAgent):
             self.last_usage = usage_total
             event, text = retry, str(retry.payload.get("text", ""))
 
-        # Absolute guarantee: scrub any spelled-out word before it ships. A no-op offline
-        # and on a clean reply; the safety net when the model leaks anyway (as it did with
-        # "a glowing ember…"). Logged so a persistent leak is visible in the run.
-        scrubbed = _redact_word(text, word)
-        if scrubbed != text:
-            obs.log("twenty_sprouts.redacted_keeper_leak", agent=self.name, turn=turn)
-            text = scrubbed
-            event.payload["text"] = text
+        # Absolute guarantee: scrub any spelled-out word before it ships — UNLESS the guesser
+        # already named it (a match), where confirming the word is the whole point. A no-op
+        # offline and on a clean reply; the safety net when the model leaks anyway.
+        if not matched:
+            scrubbed = _redact_word(text, word)
+            if scrubbed != text:
+                obs.log("twenty_sprouts.redacted_keeper_leak", agent=self.name, turn=turn)
+                text = scrubbed
+                event.payload["text"] = text
 
         # The keeper must answer, not ask: a reply still ending in a question after the
         # re-ask is skipped (live only) rather than shown asking. Redaction above can't fix
@@ -405,13 +440,14 @@ class SproutJudge(JudgedCompetition):
     def _guessed(recent_events: tuple[Event, ...], secret: str) -> bool:
         """True if the dealt word appears in ANY guesser line — a win sticks once made.
 
-        Scanning every guesser ``agent.spoke`` (not just the latest) is the fix for the
-        live bug where a correct guess was later buried under further guessing and the
-        round was wrongly scored a miss."""
-        needle = secret.lower()
+        Uses the same case-insensitive whole-word test the keeper uses to confirm a match
+        (:func:`_line_names_word`), so judge and keeper always agree on what counts as a win.
+        Scanning every guesser ``agent.spoke`` (not just the latest) is the fix for the live
+        bug where a correct guess was later buried under further guessing and the round was
+        wrongly scored a miss."""
         return any(
             e.actor == _GUESSER_NAME
             and e.kind == "agent.spoke"
-            and needle in set(_WORD.findall(str(e.payload.get("text", "")).lower()))
+            and _line_names_word(str(e.payload.get("text", "")), secret)
             for e in recent_events
         )

tests/test_twenty_sprouts.py

@@ -10,6 +10,8 @@ from __future__ import annotations
 
 import pytest
 
+from dataclasses import dataclass, field
+
 from src.agents.twenty_sprouts import (
     _WORDS,
     SecretKeeper,
@@ -17,6 +19,7 @@ from src.agents.twenty_sprouts import (
     _answer_violation,
     _classify_answer,
     _contains_word,
+    _line_names_word,
     _qa_history,
     _questions_since_guess,
     _redact_word,
@@ -142,6 +145,88 @@ def test_keeper_question_guard_is_a_passthrough_offline():
     assert event.payload["secret"] == _word_for_seed("seed-A")  # ground truth stamped on
 
 
+def test_keeper_prompt_demands_truth_and_consistency():
+    prompt = _keeper()._build_extra_prompt(StageProjection(seed="seed-A"), _qa(("Is it warm?", None)))
+    low = prompt.lower()
+    assert "never lie" in low  # don't bluff about the word
+    assert "never contradict" in low  # stay consistent across answers
+    assert "keep your secret word" in low or "keep it in mind" in low  # word stays in context
+
+
+# ── the keeper confirms a correct guess in ANY capitalization (the asked-for fix) ─────
+
+
+@pytest.mark.parametrize(
+    "text,word,names",
+    [
+        ("My guess is: COMPASS.", "COMPASS", True),
+        ("my guess is: compass", "COMPASS", True),
+        ("Is it a Compass?", "COMPASS", True),  # any capitalization is a match
+        ("it encompasses the grove", "COMPASS", False),  # whole-word, not a substring
+        ("Is it a map?", "COMPASS", False),
+    ],
+)
+def test_line_names_word_is_case_insensitive_whole_word(text, word, names):
+    assert _line_names_word(text, word) is names
+
+
+@pytest.mark.parametrize("caser", [str.upper, str.lower, str.title])
+def test_keeper_prompt_confirms_a_match_in_any_case(caser):
+    word = _word_for_seed("seed-A")
+    guess = f"My guess is: {caser(word)}."
+    prompt = _keeper()._build_extra_prompt(StageProjection(seed="seed-A"), _qa((guess, None)))
+    low = prompt.lower()
+    assert "match" in low and "named your secret word" in low
+    assert "do not deny" in low  # must not deflect a correct guess
+
+
+@dataclass
+class _ScriptedProvider:
+    """A hand-written provider stand-in (à la test_memory._RaisingIndex) that returns a
+    fixed line — so we can drive the keeper's live-path guards deterministically, no mocks."""
+
+    line: str
+    last_usage: dict = field(default_factory=lambda: {"total_tokens": 5})
+    last_reasoning: str = ""
+    model_id: str = "scripted"
+
+    def complete(self, role: str, prompt: str) -> str:
+        return self.line
+
+
+@dataclass
+class _ScriptedRouter:
+    provider: _ScriptedProvider
+    offline: bool = False  # exercise the LIVE guards (match/leak/scrub), not the stub path
+
+    def for_profile(self, key: str):
+        return self.provider
+
+
+def _scripted_keeper(line: str) -> SecretKeeper:
+    agent = SecretKeeper(_ScriptedRouter(_ScriptedProvider(line)))
+    agent.manifest = Registry.from_dir().agents["secret-keeper"]
+    return agent
+
+
+def test_keeper_acknowledges_a_match_with_the_word_intact():
+    # The guesser named the word, so confirming it WITH the word is the point — the leak
+    # scrub must stand down (no "thing" mangling of the winning acknowledgment).
+    word = _word_for_seed("seed-A")
+    guess = f"My guess is: {word.lower()}."
+    keeper = _scripted_keeper(f"Yes — {word.lower()}, you've found it!")
+    event = keeper.act(_RUN, 5, StageProjection(seed="seed-A"), _qa((guess, None)))
+    assert word.lower() in event.payload["text"].lower()  # the word survives on a match
+
+
+def test_keeper_still_scrubs_a_leak_when_it_is_not_a_match():
+    # A normal question (no guess) where the model blurts the word → still scrubbed.
+    word = _word_for_seed("seed-A")
+    keeper = _scripted_keeper(f"Yes, a {word.lower()} guides you.")
+    event = keeper.act(_RUN, 5, StageProjection(seed="seed-A"), _qa(("Is it used for direction?", None)))
+    assert word.lower() not in event.payload["text"].lower()  # leak scrubbed away
+
+
 # ── the keeper never leaks the word (the worst bug: it spelled "ember" aloud) ─────