# Impact Alerts

> *A function you depend on changed on another branch. You want to know now, not at merge time.*

**Impact alerts are Aura's way of surfacing cross-branch changes that reach into the code you are currently editing.** When a teammate on `main`, or an agent on a feature branch, modifies or deletes a function that your working copy calls, Aura raises an alert — in your terminal, in the MCP status payload, and on the dashboard. You see the impact within seconds of it being pushed to the [Mothership](/mothership-overview), not days later when you rebase. Impact alerts are how Live Sync keeps you aware of changes that are too far away to show up as a [sync conflict](/sync-conflicts) but still relevant to what you are doing right now.

## Overview

Normal version control gives you two moments of truth: the moment you pull (where you find out what happened) and the moment you merge (where you find out what broke). Everything in between is silence. In a world where a teammate and two AI agents are working in parallel, silence is where bugs breed.

Impact alerts turn the silence into a continuous feed. The feed is narrowly scoped on purpose — it only tells you about functions **you actually touch**. The dependency graph that underlies [semantic diff](/semantic-diff) is the same graph that powers impact alerts. If function `A` on your branch calls function `B`, and someone modifies `B` on another branch, you get an alert. If `B` is in a different part of the tree you never touch, you get nothing. The signal-to-noise ratio is high by construction.

A sample alert, as shown in `aura_status`:

```text
cross-branch impacts: 2 unresolved

  [impact-8f3a]  modified   billing::compute_tax
                 caller on this branch: billing::generate_invoice
                 modified by: alice        branch: main     12m ago
                 old hash: 4a21...   new hash: 9b11...

  [impact-0c71]  deleted    utils::retry_with_backoff
                 caller on this branch: http::fetch_user
                 deleted by: claude-agent  branch: feat/fetch  3m ago
```

Each alert carries: the affected function, how you depend on it, who changed it, on which branch, and what kind of change (modified, deleted, renamed, signature-changed). You act on it by fixing your caller, adjusting your plan, or acknowledging the alert.

## How It Works

Impact alerts are a byproduct of two systems working together: the logic graph and Live Sync's push channel.

```text
    ┌── alice on main ─────────┐         ┌── Mothership ──┐         ┌── you on feat/x ─────┐
    │ edit billing::compute_tax│  push   │                │  fan-out │ scan my callers of    │
    │ (new AST hash)           ├────────>│ route fn push  ├─────────>│   compute_tax         │
    └──────────────────────────┘         └────────────────┘          │ any? -> raise alert   │
                                                                      └───────────────────────┘
```

When a function body arrives via Live Sync from another branch, Aura does three things:

1. **Check your logic graph.** Does any function on your current branch *call* the modified function? If no, the event is filed in history but no alert is raised.
2. **Compare signatures.** If the function's argument list or return type changed, the alert severity is upgraded — this is more than a body tweak; callers almost certainly need updating.
3. **Attach a proof request.** If the caller and callee are on different branches with known divergence, Aura can enqueue a background [aura_prove](/prove) run to check whether your caller is still satisfied by the new body. The result attaches to the alert.

Deletion alerts are a special case. If the incoming event says "function removed" and you have callers, the alert is marked **critical** — your branch will not build against the other branch until you fix the callers or the callee returns.

## Fetching impacts from MCP

Agents see impacts automatically at session start (it is part of the `aura_status` payload), and they should re-check periodically during long sessions. Explicitly:

```bash
# Via MCP:
aura_live_impacts

# Via CLI:
aura live impacts
```

Output (`aura live impacts --json`):

```json
{
  "unresolved": [
    {
      "id": "impact-8f3a",
      "kind": "modified",
      "target_fn": "billing::compute_tax",
      "caller_fn": "billing::generate_invoice",
      "remote_branch": "main",
      "remote_author": "alice",
      "old_hash": "4a21...",
      "new_hash": "9b11...",
      "ts_ms": 1740000000000
    }
  ]
}
```

## Resolving an alert

When you have addressed an alert — either by updating your caller, adjusting your plan, or deciding it does not apply — mark it resolved:

```bash
# Via MCP:
aura_live_resolve impact-8f3a --note "Updated generate_invoice to pass region."

# Via CLI:
aura live resolve impact-8f3a --note "..."
```

Resolution is durable. It records who resolved it, when, and why. Re-opening an alert is allowed; Aura will raise a fresh alert with a link to the prior resolution so you can see the history.

There is also a dismissal path for alerts that are not actionable:

```bash
aura live resolve impact-8f3a --dismiss --reason "Unrelated — caller no longer uses this path."
```

Dismissed alerts do not re-appear unless the function changes again.

## Alert kinds

| Kind | Meaning | Typical action |
|---|---|---|
| `modified` | Function body changed | Re-read the body, check your assumptions, possibly re-prove |
| `signature_changed` | Arguments or return type changed | Update every caller on your branch |
| `deleted` | Function removed | Restore, inline, or replace callers |
| `renamed` | Function moved/renamed (same `aura_id`) | No code fix needed — update imports if the rename crosses modules |
| `moved_file` | Function moved across files | Update imports |

## Acting on impacts as an AI agent

Agents running inside Aura should treat unresolved impacts as **blocking** for any commit that touches the caller:

```text
  agent turn:
    1. call aura_status
    2. if cross-branch impacts > 0:
         call aura_live_impacts
         for each impact:
            read caller + new callee body
            fix or decide not-applicable
            call aura_live_resolve with note
    3. proceed with original task
```

This is already wired in the MCP pipeline — the `aura_status` payload surfaces `team.pending_impacts` and the Claude Code system prompt instructs agents to handle them before other work.

## Config

Impact alerts are on whenever Live Sync is on. You can tune the scope:

```toml
[live.impacts]
# Only raise for functions I directly call. If false, also alerts for 2nd-order deps.
direct_callers_only = true

# Ignore impacts older than this. Useful after a long absence when the feed is noisy.
max_age_days = 14

# Suppress alerts from these branches (e.g. long-running experiment branches).
ignore_branches = ["experiment/*", "wip/*"]
```

## Troubleshooting

If you expect an alert and do not see one, check that the remote branch has actually pushed the change to the Mothership (`aura live sync status --peer alice`). A local commit that has not been pushed cannot raise an impact.

If you see spurious alerts for functions you never touch, the caller graph may be stale. Rebuild it:

```bash
aura graph rebuild
```

> **Gotcha:** Impact alerts are cross-branch. If you and Alice are on the same branch, her push is applied to your working copy directly (possibly producing a [sync conflict](/sync-conflicts)), not raised as an impact.

## Severity and escalation

Alerts have three severity levels and the UI treats them differently:

- **info** — body change only, caller likely unaffected. Shown in status; does not interrupt.
- **warn** — body change with semantic impact (branches taken, error paths), or signature change. Surfaces in `aura_status` and is expected to be addressed.
- **critical** — function deleted, or signature change that provably breaks your caller. Blocks commits that touch the caller until resolved or explicitly dismissed.

An AI agent flow treats `critical` as a hard gate:

```text
  on every commit attempt:
    impacts = aura_live_impacts()
    for each impact in impacts where severity == critical:
      if impact.caller in changeset:
        REFUSE commit, request resolution
```

The CLI pre-commit hook enforces the same rule.

## Detection latency

An end-to-end walk of how fast an alert surfaces:

```text
    t+0.0s   teammate saves, scan detects change
    t+5.0s   next sync tick on their side pushes to Mothership
    t+5.1s   Mothership routes event to your peer
    t+5.2s   your peer cross-references caller graph
    t+5.2s   alert raised (visible in aura_status, CLI, dashboard)
```

Under five and a half seconds from their save to your alert on a healthy Mothership link. Longer if the teammate's sync window is extended for metered networks.

## What an alert is *not*

Impact alerts are not a test signal. They do not tell you "your code is broken" — they tell you "a thing you depend on moved." Whether that movement breaks you is still your call. Aura can optionally run [aura_prove](/prove) against the caller to give a yes/no answer, but that is a separate subsystem layered on top of the alert.

Impact alerts are also not a *Git* rebase replacement. Rebasing still integrates commits cleanly in Git history; the alert just tells you, before the rebase, that the rebase is going to touch relevant ground.

## Historical replay

Sometimes you want to see all impacts over a time window — for retros, or to understand a bug that landed yesterday:

```bash
aura live impacts --since 1d --include-resolved
```

This prints every impact that fired, whether resolved or dismissed, with timestamps and resolution notes. It is a useful post-mortem trail when a bug correlates with "the day Alice and Bob were both in `billing::`".

## See Also

- [Live Sync overview](/live-sync-overview)
- [Sync conflicts](/sync-conflicts)
- [Semantic diff](/semantic-diff)
- [Mothership overview](/mothership-overview)