Propose comment-triggered agents ("tag an agent") — tracking #159

[k5s-bot]

What

Files the ticket asked for: a way to trigger agents via comments and to
"tag" a specific agent from a comment. Creates tracking issue #159 and adds
a grounded proposal doc (docs/proposals/comment-triggered-agents.md).

This PR adds documentation only — no behavior change. It exists so the
proposal is reviewable in-repo alongside the issue; the actual implementation
should follow once a direction is chosen on #159.

Why it doesn't work today (grounded in the code)

• parseGithubEvent (apps/integration-gateway/src/webhooks/github.ts) only
  makes issues.labeled / pull_request.labeled actionable;
  issue_comment.created → { kind: "ignored" }. Commenting never runs an
  agent (documented in docs/integrations-gateway.md).
• IntegrationRoute.spec.match keys on { source, event, action, labelName }
  only (crd-integration-route-registry.ts, ADR 0024) — no mention/command
  selector and no @handle → Agent resolution, so a comment can't address a
  specific agent.
• GitHub-App accounts generally can't be assignees (ADR 0024 rejected "assign
  the bot" for this), so @mention-style tagging needs real design.

Proposed solutions (see the doc for full tradeoffs)

• A (recommended): slash-command grammar (/agent <name> …) → extend
  IntegrationRoute.match with event: "issue_comment" — reuses the existing
  deterministic CRD dispatch.
• B: @mention handle → Agent resolver (annotation/metadata.name);
  composes with A.
• C: mentionable bot + reaction-based ack (👀→🚀→✅) as the re-trigger/idempotency gesture.
• D: baseline — keep comments a no-op, lean on the existing session page.

Plus cross-cutting concerns: loop prevention (senderIsBot drop + required
prefix), identity gating (reuse identityResolver.resolve), comment-id dedupe,
and fast 202 ack.

Closes #159 is intentionally not used — the issue tracks the implementation;
this PR only lands the proposal.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Cp7xF4sPhZ59pTUg72Kg9j