Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion concepts/governance-signals.mdx
Original file line number Diff line number Diff line change
@@ -1,13 +1,13 @@
---
title: "Governance signals"
description: "Operator-actionable observations from Mnemom's platform detectors — fleet drift, value fault lines, coherence drops, behavior drift. Surfaced to operators (UI, webhook, REST) and to application composers, never auto-injected into agent prompts."

Check warning on line 3 in concepts/governance-signals.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mnemomllc) - vale-spellcheck

concepts/governance-signals.mdx#L3

Did you really mean 'Mnemom's'?
sidebarTitle: "Governance signals"
icon: "siren"
---

# Governance signals

**Governance signals** are operator-actionable observations produced by Mnemom platform detectors. They surface fleet-shaped concerns — coherence drift across a team, value fault lines between agents, fleet topology changes, per-agent behavior drift — that an *operator* (CISO, org admin, team admin, on-call SRE) needs to see and act on.

Check warning on line 10 in concepts/governance-signals.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mnemomllc) - vale-spellcheck

concepts/governance-signals.mdx#L10

Did you really mean 'Mnemom'?

They are deliberately distinct from the [per-turn advisories](/concepts/safe-house) that the gateway injects into an agent's next prompt. The architectural commitment, ratified in [ADR-048](https://github.com/mnemom/scale/blob/main/decisions/ADR-048-governance-signals-layering.md), is:

Expand All @@ -30,7 +30,7 @@

A governance signal lives in **three operator surfaces** simultaneously:

1. **Web UI** at `app.mnemom.ai/dashboard/teams/{teamId}/governance` (and per-agent at `/dashboard/agents/{uuid}/governance`). Filterable list, severity badges, ack/resolve/dismiss workflow.
1. **Web UI** at `mnemom.ai/dashboard/teams/{teamId}/governance` (and per-agent at `mnemom.ai/dashboard/agents/{uuid}/governance`). Filterable list, severity badges, ack/resolve/dismiss workflow.
2. **Webhook** events: `governance.signal.fired`, `governance.signal.acknowledged`, `governance.signal.resolved`, `governance.signal.dismissed`, `governance.escalation.triggered`. HMAC-SHA256 signed POSTs (`X-Mnemom-Signature: sha256=…`) following the AAP webhook contract.
3. **REST API**: `GET /v1/orgs/:org/governance/signals`, `GET /v1/teams/:team/governance/signals`, `GET /v1/agents/:agent/governance/signals`, plus state-transition endpoints. See [Governance Signals Schema](/specifications/governance-signals-schema).

Expand All @@ -54,7 +54,7 @@
- **`dismissed`** — operator marked as not actionable (noise, redundant).
- **`expired`** — TTL elapsed without operator action; configurable per posture, default 30 days.

The schema's partial unique index on `(scope, scope_id, source, pattern_type) WHERE status='open'` makes detection idempotent: repeated cron emissions of the same condition refresh the open row in place rather than stacking. This is the architectural fix to the symptom that triggered this work — a sovereign agent receiving the same `cluster_partition` paragraph 2× per turn for weeks.

Check warning on line 57 in concepts/governance-signals.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mnemomllc) - vale-spellcheck

concepts/governance-signals.mdx#L57

Did you really mean 'schema's'?

Check warning on line 57 in concepts/governance-signals.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mnemomllc) - vale-spellcheck

concepts/governance-signals.mdx#L57

Did you really mean 'cron'?

## Notification destinations

Expand All @@ -62,10 +62,10 @@

- **`webhook`** — generic HMAC-signed POST to a URL of your choice. Mirrors AAP webhook contract.
- **`slack`** — incoming-webhook POST with [Block Kit](https://api.slack.com/block-kit) payload. Severity-color border, action button to "Acknowledge in dashboard."
- **`email`** — Resend-backed HTML + plaintext.

Check warning on line 65 in concepts/governance-signals.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mnemomllc) - vale-spellcheck

concepts/governance-signals.mdx#L65

Did you really mean 'plaintext'?
- **`pagerduty`** — Events API v2 with stable `dedup_key` so coalesced detections don't duplicate incidents.

A destination's `filter` narrows what it receives (sources, severities, scopes, pattern_types). [Escalation rules](/guides/operating-governance-signals#escalation-rules) bind a predicate to a list of destination IDs and support rate-based gating (`threshold_count` + `window_minutes`) for "fire only if N matching signals occurred in M minutes."

Check warning on line 68 in concepts/governance-signals.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mnemomllc) - vale-spellcheck

concepts/governance-signals.mdx#L68

Did you really mean 'severities'?

Check warning on line 68 in concepts/governance-signals.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mnemomllc) - vale-spellcheck

concepts/governance-signals.mdx#L68

Did you really mean 'pattern_types'?

Test a destination from the CLI:

Expand All @@ -87,7 +87,7 @@
## Related

- [Sideband detection](/concepts/sideband-detection) — the detector layer (unchanged; only the delivery surface moved).
- [Governance Signals Schema](/specifications/governance-signals-schema) — table layout, RPCs, RLS.

Check warning on line 90 in concepts/governance-signals.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mnemomllc) - vale-spellcheck

concepts/governance-signals.mdx#L90

Did you really mean 'RPCs'?
- [Operating governance signals](/guides/operating-governance-signals) — operator runbook for ack/resolve/dismiss + destinations + rules.

Check warning on line 91 in concepts/governance-signals.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mnemomllc) - vale-spellcheck

concepts/governance-signals.mdx#L91

Did you really mean 'runbook'?
- [Sovereign-agent composition](/guides/sovereign-agent-composition) — application-side pattern for opting sovereign agents into governance-signal context.
- [ADR-048](https://github.com/mnemom/scale/blob/main/decisions/ADR-048-governance-signals-layering.md) — the architectural decision.
2 changes: 1 addition & 1 deletion guides/operating-governance-signals.mdx
Original file line number Diff line number Diff line change
@@ -1,17 +1,17 @@
---
title: "Operating governance signals"
description: "Operator runbook for ack/resolve/dismiss workflow, notification destinations (Slack/email/PagerDuty/webhook), and escalation rules."

Check warning on line 3 in guides/operating-governance-signals.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mnemomllc) - vale-spellcheck

guides/operating-governance-signals.mdx#L3

Did you really mean 'runbook'?
sidebarTitle: "Operating governance signals"
icon: "list-check"
---

# Operating governance signals

[Governance signals](/concepts/governance-signals) are observations operators see and act on. This guide walks through the runbook.

Check warning on line 10 in guides/operating-governance-signals.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mnemomllc) - vale-spellcheck

guides/operating-governance-signals.mdx#L10

Did you really mean 'runbook'?

## Daily flow

1. **Triage** the open queue at `app.mnemom.ai/dashboard/teams/{teamId}/governance` (or via `mnemom governance signals list --team <id> --status open`).
1. **Triage** the open queue at `mnemom.ai/dashboard/teams/{teamId}/governance` (or via `mnemom governance signals list --team <id> --status open`).
2. **Acknowledge** signals you're investigating. Records `acknowledged_actor_role` per [ADR-046](https://github.com/mnemom/scale/blob/main/decisions/ADR-046-audit-actor-model.md) — captures whether you acted as `org_admin`, `team_admin`, etc.
3. **Resolve** with a `resolution_status`:
- `action_taken` — you (or a sovereign agent) made changes (rebalanced team, refreshed cards, …).
Expand Down Expand Up @@ -58,7 +58,7 @@
--config '{"to":["security-oncall@yourco.com"],"from":"governance@yourco.com"}'
```

Resend-backed HTML + plaintext.

Check warning on line 61 in guides/operating-governance-signals.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mnemomllc) - vale-spellcheck

guides/operating-governance-signals.mdx#L61

Did you really mean 'plaintext'?

### PagerDuty

Expand Down Expand Up @@ -125,7 +125,7 @@
Predicate keys (AND-folded):

- `source` — exact source match.
- `pattern_type` — exact pattern_type match.

Check warning on line 128 in guides/operating-governance-signals.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mnemomllc) - vale-spellcheck

guides/operating-governance-signals.mdx#L128

Did you really mean 'pattern_type'?
- `severity_min` / `severity_max` — bound on severity.
- `scope` — exact scope match.
- `team_id` — narrow to one team.
Expand All @@ -143,11 +143,11 @@
--destinations dest-pagerduty-id
```

### Dedup across rules

Check warning on line 146 in guides/operating-governance-signals.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mnemomllc) - vale-spellcheck

guides/operating-governance-signals.mdx#L146

Did you really mean 'Dedup'?

If two rules both route to the same destination, the dispatcher dedups — one Slack message per signal, not two. Each contributing rule's `fire_count` and `last_fired_at` still get bumped.

Check warning on line 148 in guides/operating-governance-signals.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mnemomllc) - vale-spellcheck

guides/operating-governance-signals.mdx#L148

Did you really mean 'dedups'?

## Coverage rollup

Check warning on line 150 in guides/operating-governance-signals.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mnemomllc) - vale-spellcheck

guides/operating-governance-signals.mdx#L150

Did you really mean 'rollup'?

`GET /v1/orgs/:org_id/governance/coverage?days=30` returns a per-(source, severity) aggregate over the window:

Expand Down
Loading