GateGraph

Reality scenarios

GateGraph is designed for operational pressure, not ideal demos.

See docs/REALITY_SCENARIOS.md for concrete drift scenarios such as approval fatigue, retry loops, semantic boundary evasion, budget blindness, silent schema evolution, and rule cascade.

The core idea: governance matters most when humans and systems begin to normalize exceptions.

Start here

For orientation, use START_HERE.md. Current release: v0.28.2_STABLE · base v0.27.0_STABLE · Phase: RESOURCE_GATE_01 Capability Verify Adapter · Status: stable

Fastest local trial path:

1. docs/INTEGRATOR_QUICKSTART.md
2. examples/integrator/local_decision_flow.py
3. docs/INTEGRATOR_TRIAL_BUNDLE.md
4. examples/integrator/operator_trial_bundle.py

The trial bundle is local single-node only. It does not add Runtime-Authority, policy mutation, external calls, secret resolution, SaaS, Relay, Mobile, or Multi-Node behavior.

AI agents can delete files, call APIs, and trigger external actions. GateGraph decides whether an agent action is allowed to proceed — before it happens.

GateGraph is a local, single-node, evidence-first governance/control layer for bounded AI-agent actions. It evaluates requested capabilities, issues capability tokens only when policy allows them, blocks unsafe paths fail-closed, and records decisions for audit/replay.

Two-minute example

python -m pip install -e .
export GATEGRAPH_ALLOW_DEV_KEYRING=1  # dev keyring only: local trial mode, not production key material
# Windows PowerShell: $env:GATEGRAPH_ALLOW_DEV_KEYRING="1"
gategraph init --reset

Create a destructive task request:

cat > delete-task.json <<'JSON'
{
  "task_id": "DEMO-DELETE-001",
  "task_type": "file_operation",
  "requested_capabilities": ["delete_files"],
  "input_source": "local",
  "data_sensitivity": "internal",
  "secrets_involved": false,
  "projected_cost_units": 1
}
JSON

gategraph evaluate --task delete-task.json

Expected output excerpt:

{
  "ok": true,
  "task_id": "DEMO-DELETE-001",
  "decision": "require_approval",
  "risk_level": "high",
  "risk_reason": "Human approval is required for this request boundary.",
  "selected_rule_id": "RULE-002",
  "matched_rule_ids": ["RULE-002"],
  "token_issued": false,
  "token_id": null
}

What this shows: the agent asked for delete_files; GateGraph did not issue a capability token. The action cannot proceed through the enforcement boundary without explicit authority.

Governance flow

flowchart LR
    A[Agent task request] --> B[Governance decision]
    B --> C{Capability allowed?}
    C -- yes --> D[Capability token boundary]
    C -- no --> X[Fail closed / require approval]
    D --> E[Enforcement gate]
    E --> F[Session budget guard]
    F --> G[Runtime guard]
    G --> H[Audit event]
    H --> I[Replay / explanation reference]

Loading

Why the name?

Gate: every action must pass an explicit boundary before execution.
Graph: decisions, evidence, audit events and replay references form a traceable relationship graph rather than a loose log stream.

Core principles

• Fail closed — missing authority, invalid tokens, unknown context and unsupported transitions stop rather than continue.
• Deterministic — evidence, replay ordering and explanation artifacts are designed to be reproducible.
• No second truth — docs and landing pages summarize source artifacts; they do not become policy.
• Proposal ≠ authority — reviews, scenarios and explanations can inform humans, but they do not mutate governance by themselves.

Quick links

• Start here: START_HERE.md
• Static landing page: docs/index.html
• Quickstart: docs/QUICKSTART.md
• Integrator trial path: docs/INTEGRATOR_QUICKSTART.md
• Integrator onboarding: docs/INTEGRATOR_ONBOARDING.md
• Minimal examples: examples/integrator/
• Architecture: ARCHITECTURE.md
• Governance model: GOVERNANCE.md
• Invariants: INVARIANTS.md
• Security model: SECURITY_MODEL.md
• OWASP agentic mapping: OWASP_AGENTIC_AI_MAPPING.md
• Non-scope: NON_SCOPE.md

What GateGraph is not

GateGraph is not an autonomous agent, not a SaaS dashboard, not a live orchestration platform, not an automatic remediation system, and not a compliance guarantee.

Current production boundary

Current boundary: single-node / local-protected, evidence-first governance/control. Multi-node runtime authority, distributed governance, hosted deployment and autonomous policy mutation remain out of scope. This boundary does not create production certification. Deferred scope remains tracked in docs/SCOPE_BACKLOG.md.

Minimal integration examples

For the smallest executable local trial path, run python examples/integrator/local_decision_flow.py. For copy/paste task payloads, use examples/integrator/read_only_task.json and examples/integrator/destructive_task.json. These examples are decision-boundary demonstrations only; they do not add execution authority.

Evidence

GateGraph ships with a large deterministic evidence suite covering enforcement, capability-token boundaries, runtime/session guards, replay/explanation boundaries, release hygiene and public-surface constraints.

Local verification:

python tests/evidence_ci.py

Focused release/public-surface triage:

GATEGRAPH_EVIDENCE_PROFILE=release python tests/evidence_ci.py

Repository metadata suggestion

Suggested GitHub description:

GateGraph decides if an AI agent action may proceed — before it executes.

Suggested topics:

ai-governance, agent-security, llm, capability-tokens, python, auditability, fail-closed

These values are repository metadata, not runtime behavior.