swarm-master/swarm-common/obsidian-vault/will/will-shared-zap/Projects/Atlas/Gateway Approval Runbook.md

Gateway Approval Runbook

Created: 2026-05-14 Owner: Will / Atlas Related: Safer Autonomy and Permission Tiers

Goal

Make Discord and Telegram behavior predictable: Atlas should act immediately on safe work, ask for bounded operational changes, and block destructive or sensitive actions until Will gives exact approval.

Quick examples

Tier 0: proceed

User: "Atlas, check gateway status."

Atlas may inspect process/service status, gateway logs, and config keys without asking. Atlas should not print secrets.

Expected response shape:

• Status summary.
• Any warnings.
• What was not changed.

Tier 1: proceed within scope

User: "Atlas, create a Kanban task for this bug."

Atlas may create the task if the board/project is clear from the current context. If the board/project is not clear, ask one clarifying question or use the current active board when obvious.

Expected response shape:

• Task title/id.
• Assignee if known.
• Any assumptions.

Tier 2: ask or require explicit instruction

User: "Atlas, restart the gateway."

If the user explicitly requested the restart in the current thread, Atlas may proceed through the configured command approval flow. If the request is ambiguous, Atlas should ask:

"Restart Hermes gateway on this machine? This may briefly interrupt Telegram/Discord responses. Rollback is hermes gateway start if it fails."

Expected response shape after action:

• Exact target restarted.
• Verification result.
• Any follow-up needed.

Tier 3: block for exact approval

User: "Atlas, delete old sessions/logs."

Atlas must not delete until the target, retention window, backup/rollback status, and approver are explicit.

Expected question:

"Please confirm: delete Hermes session/log files under <exact path> older than <retention>? This is irreversible unless backed up. Should I create a backup first?"

If approval is not exact, block or ask again.

Approval rules

• Use /approve and /deny where the gateway has a pending command approval flow.
• Do not treat emoji reactions as approval for Tier 3.
• Do not treat "sure", "ok", or "do it" as enough for destructive actions unless the prior prompt named the exact target and action.
• Prefer Will approval for Tier 3 actions.
• Record durable approvals in Kanban comments when the work is board-tracked.

Agent blast-radius checklist

Before enabling or running a gateway-triggered agent action that changes state, state the blast radius explicitly:

• Filesystem scope: exact paths/repos/vaults the agent may read/write; everything else is out of scope.
• Network egress: allowed services/domains/channels/repos; no uploads or third-party sends outside the named target.
• Credential exposure: credentials are referenced by presence/source only; secret values are never pasted into chat, notes, logs, commits, or external tools.
• Destructive command approval mode: destructive or broad commands require approvals.mode: manual or smart; no --yolo / approval-off for gateway/profile automation unless Will explicitly approved a sandbox.
• Rollback/checkpoint status: checkpoint, git branch/worktree, backup, snapshot, or recovery command is known before mutation.
• Human approval gate: Tier 2/3 prompts name the exact target, effect, rollback/stop condition, and approver before execution.

Message templates

Tier 2 approval request

"I can do that, but it is Tier 2 because it changes persistent state. Target: <target>. Blast radius: <scope>. Expected duration/cost: <duration/cost>. Rollback/stop: <rollback>. Approve?"

Tier 3 approval request

"This is Tier 3. Please confirm the exact action: <action> on <target>. Expected irreversible/sensitive effect: <effect>. Backup/rollback status: <status>. Reason: <why>. I will not proceed without exact approval."

Safe completion reply

"Done: <what changed>. Verified by <check>. I did not <explicit non-actions if ambiguity/risk existed>."

Gateway operator checklist

Before enabling a new gateway workflow:

• Identify the highest possible risk tier.
• Define allowed channels/users and target resources.
• Decide whether Tier 2 actions can use /approve or must block into Kanban.
• Ensure Tier 3 cannot run from vague chat approval.
• Test at least one proceed case, one ask case, and one block case in a sandbox chat/thread.