Redefine 👍🏼👎🏼 as a confirmation contract with fixed yes/no semantics

[williamthorsen]

Problem

The 👍🏼👎🏼 marker is currently defined in shared/AGENTS.md as ending "any yes/no question (approval, decisions, confirmations)". In practice, agents append it to questions like:

• "Apply these revisions and re-present, or anything else to adjust first? 👍🏼👎🏼"
• "Approve the plan, or any revisions? 👍🏼👎🏼"

When the user replies "yes", agents treat the response as ambiguous and ask for clarification — wasting a turn. The dual failure mode is "inferred yes": the agent treats positive commentary or vague approval as confirmation and proceeds when it shouldn't, leaving the user to mash Esc.

Trying to forbid "or X" phrasings on the production side is brittle: sometimes the alternative clause is genuine flavor about what declining means, sometimes fluff, and agents can't reliably tell.

Context

Every existing 👍🏼👎🏼 usage in the codebase is functionally a confirmation prompt: "proceed?", "approve?", "looks right?", "ready to merge?". The marker's actual semantic role is "I'm asking you to confirm a proposed action" — not the more general "this is a yes/no question". Any alternative clause attached to such a prompt is descriptive colour about what declining entails, not a second option requiring disambiguation.

Related convention: the recommendation-gradient (_data/recommendation-gradient.md) covers the numbered-options case (2+ named, equal-weight choices). The 👍🏼👎🏼 marker covers the confirmation case. The current rule conflates confirmation with "yes/no question", which is what creates the ambiguity.

Solution

Redefine the marker by semantic role rather than grammatical shape, and codify a fixed bidirectional comprehension contract.

Production side: The 👍🏼👎🏼 marker indicates a confirmation prompt — the agent is asking the user to confirm a proposed action. Agents may include descriptive clauses about what declining would entail; phrasing is not constrained.

Comprehension contract:

• A clear affirmation ("yes", "yep", "yeah", "looks good", "go ahead", "approved", "ship it", 👍, etc.) → proceed with the proposed action.
• A clear negation ("no", "nope", "not yet", "stop", "wait", 👎, etc.) → do not proceed; await user direction.
• Anything else — including positive commentary that is not a clear go-ahead — is conversation, not an inferred yes.

The marker is the agent's promise to the user: if you clearly affirm, I will proceed; if you do not clearly affirm, I will not proceed. Two specific failure modes are prohibited:

• The agent must never re-ask a clear affirmation as ambiguous.
• The agent must never infer affirmation from positive-but-not-clearly-affirmative responses.

Files affected:

• packages/agents/content/guidance/shared/AGENTS.md § Prompt formatting — rewrite the marker's definition and add the comprehension contract.
• packages/agents/content/skills/collaboration/SKILL.md § Asking questions — short pointer reinforcing the contract at the point where agents form questions during interactive work.

No skill-body changes elsewhere — the problematic prompts are improvised at runtime, not written into individual skill bodies.

Acceptance criteria

• shared/AGENTS.md § Prompt formatting defines 👍🏼👎🏼 as a confirmation contract, not a marker for "yes/no questions".
• The bidirectional comprehension contract is documented explicitly: clear affirmation → proceed, clear negation → don't proceed, anything else → conversation.
• Both failure modes are prohibited in writing: (1) re-asking a clear affirmation as ambiguous; (2) inferring affirmation from positive-but-not-clearly-affirmative responses.
• collaboration/SKILL.md § Asking questions reinforces the contract via a pointer to the canonical location in shared/AGENTS.md.
• Existing 👍🏼👎🏼 usages elsewhere in the codebase remain valid under the new definition (spot-check; no rewrites expected).