Standardize operator gates with structural to:user messages

[omriariav]

Motivation

amq-noc now has a deterministic status model for teams and agents: running, stale, waiting, and needs-you. The important distinction is that needs-you must come from a structural signal that the human/operator is the required actor, not from prose in an agent-to-agent message.

Today AMQ already supports the right primitive: amq send --to user .... A message addressed to user lands in agents/user/inbox/... and can be observed by NOC as a human action item. The problem is producer discipline: most real squad traffic still says things like "operator-held", "pending operator instruction", "manual RC", or "release mechanics" inside agent-to-agent threads. That is useful evidence, but it is not a deterministic human gate.

Recent local mailbox scan across active AMQ/amq-squad workspaces under /Users/omri.a/Code found roughly 21,899 AMQ message files, only 2 message files under agents/user/..., and hundreds of messages with operator/user/manual-approval prose. Concrete example: a PM OS release hold was from: cpo, to: ["cto"], subject Ack: final 3.1.0 RC accepted, with body text saying release remains operator-held pending explicit instruction. NOC correctly cannot classify that as needs-you without guessing.

By contrast, the new amq-noc manual RC gate uses a structural ask:

amq send --to user \
  --thread gate/manual-rc \
  --kind question \
  --subject "APPROVAL: manual RC test + commit decision" \
  --body "Holding the slice uncommitted. Need your decision: test the RC, then approve commit or request changes."

That surfaces as fullstack needs you and clears when the operator replies.

Proposal

Standardize an operator gate protocol across AMQ skills and amq-squad guidance:

1. When a human/operator action is required, emit a structural message addressed to user.
2. Use a stable gate thread: gate/<topic>.
3. Use --kind question for approvals/choices/manual tests and action subjects such as APPROVAL: <decision>.
4. Use --kind decision with DONE: <goal> when the team goal is complete and needs human closeout.
5. Keep ordinary agent coordination in p2p/decision threads. Do not send to:user for FYIs, ACKs, routine peer reviews, or agent-owned blockers.
6. If the escalation owner is CTO/lead, CTO/lead decides whether to escalate, but the actual human action must still be represented as a to:user gate so NOC and other tooling can observe it.

Implementation Plan

We will submit a PR that updates the shared repo docs/skills, likely including:

• skills/amq-cli/SKILL.md: add a first-class "Operator Gates" section under Messaging, with canonical commands and anti-patterns.
• skills/amq-spec/SKILL.md and references/spec-workflow.md: after final decision/presentation, if implementation or release is waiting on user approval, the initiator raises a to:user gate; partner agents do not implement from a spec decision alone.
• skills/*/amq-squad/SKILL.md and/or bootstrap/team-rules templates: keep "user escalations route through CTO" but add the structural to:user requirement for the actual operator action.
• Any generated bootstrap prompt that currently mentions APPROVAL: / DONE: should be checked for consistency with stable gate/<topic> threads.

Acceptance Criteria

• Skills clearly distinguish:
  • agent-to-agent work waits => p2p/decision messages, visible as waiting/stale depending on liveness;
  • human/operator action => to:user gate, visible as needs-you.
• Examples include exact copy-pasteable amq send --to user --thread gate/<topic> ... commands.
• Anti-pattern is explicit: prose like "operator-held" in an agent-to-agent ACK is not a gate.
• amq-noc can keep deterministic classification without LLM/prose guessing.

We intend to implement this and submit a PR.