Inside co-gas Cognames: clue the whole board, not just the target

Richard here. I work on the co-gas policies. Our agent helped turn the source and replay notes into this explanation, and I reviewed it before posting.

This covers Cognames 0.5.11, the standard two-spymaster game, and our checked-in co-gas-cognames-codebook planner. The game supplies the operatives; our policy controls one spymaster and sends a one-word clue plus a number. That split matters because we choose the hint, but we do not choose which card the operative contacts.

What the spymaster is solving

The spymaster sees the 25-word board and the hidden key: our agents, the other team's agents, bystanders, and the assassin. The first team to reveal all of its agents wins. An enemy or bystander contact ends the turn. An assassin contact ends the game immediately against the guessing team.

A clue like ANIMAL 2 invites up to three guesses: the named two plus one bonus guess. So a clue is not safe merely because it fits two friendly words. We also have to ask what every other unrevealed word might attract.

How we choose a clue

The planner has a small, hand-checked semantic table rather than a language-model call. It searches in this order:

try a known multi-card group whose targets are all ours and whose decoy risk is zero
else try one semantic clue shared by two or more of our words, with zero decoy risk
else give a safe one-card synonym
else emit a legal, deterministic code word for the first remaining friendly card

For example, BIOLOGY 2 can cover CELL and MICROSCOPE when both are ours. Before using it, the policy checks that no named target is off-team and that the current board contains no known lure for BIOLOGY. It applies the same test to one-card clues. The risk table gives the assassin the highest cost, but any known enemy or bystander lure is enough to reject the clue.

The code word at the bottom is a liveness fallback. It is generated from the target card's board index and adjusted until it passes the clue validator. It keeps the player from sending malformed output, but a built-in operative is not expected to understand an opaque code as well as a normal semantic clue.

Three gotchas from real games

The bonus guess changes clue safety. In one completed game, COVER 1 led correctly to HOOD, then the operative used its extra guess on the assassin FACE. Our lure table therefore considers likely follow-up words even when the clue number is one.

Meaning is board-dependent. ANIMAL may look harmless for an animal card, but it is rejected when DUCK is an unrevealed off-team lure. Likewise, a clue can be safe on one board and dangerous on the next. We test the candidate clue against the live board every turn.

Legal-looking words can still fail validation. The live game rejects clues that equal or contain an unrevealed board word, and hosted episodes exposed a small set of geographic clues that also had to be excluded. We check locally first, then send the exact current reply.decision shape.

What the replays changed

An audit of 16 completed episodes found that an earlier version went 7-9 and averaged only 1.05 named cards per clue. That pushed us to add replay-proven multi-card groups. The next 12-episode test was useful counterevidence: the new planner produced only one multi-card clue in 63 clue turns, finished 4-8, and was not promoted. The idea was sound on its fixture boards but too rare to improve the broader distribution.

Our main open problem is predicting the operative's extra association without overfitting a growing blacklist. The deterministic table is easy to inspect, but novel word pairs remain genuinely uncertain.

How do you estimate bonus-guess risk before choosing a clue? Do you prefer a small set of proven two-card groups or generate groups from the live board? What evidence is enough for you to mark a semantic lure unsafe? When no clean semantic clue exists, what fallback gives the operative the best chance while staying legal?