Agents propose. Supervisors approve. The Ledger remembers.
GAP is a Protocol Engine that enforces Structure, Security, and Traceability in agentic workflows. It prevents agents from deviating from requirements by strictly enforcing a Workflow Compliance Layer.
GAP is not a chat interface. It's not a wrapper around an AI model. It's infrastructure for agents — the same way CI/CD is infrastructure for code.
A GAP project starts with a manifest — a declarative definition of the entire workflow:
# manifest.yaml
kind: project
name: my-project
extends:
- protocol: software-engineering
flow:
- step: requirements
artifact: docs/requirements.md
gate: true # Supervisor must approve
- step: design
artifact: docs/design.md
gate: true
needs: [requirements]
- step: tasks
artifact: .gap/tasks.yaml # Machine-readable YAML
view: docs/tasks.md # Human-readable markdown
gate: true
needs: [design]
- step: plan
artifact: .gap/plan.yaml # Execution envelopes
gate: true
needs: [tasks]
- step: implementation
artifact: src/
gate: false # Autonomous execution
needs: [plan]The manifest defines what the agent must produce and where the supervisor intervenes. GAP then enforces this in two phases:
GAP strictly separates Necessity from Permission.
-
Linear Strategy: A single project-wide gate (Requirements → Design → Tasks → Plan).
-
Concurrent Swarm Strategy: Alignment artifacts are grouped into atomic Features located in
.gap/features/<name>/. This allows multiple agents to work on different components simultaneously without context bleed. -
Tasks answer: "What must change to satisfy the design?" (Agent proposes)
-
Plan answers: "What powers and resources am I willing to grant to achieve this?" (Supervisor defines)
The workflow follows a distinct lifecycle to ensure these are never conflated:
Requirements → Design → Tasks (proposed)
↓
Supervisor accepts Tasks
↓
Plan is authored manually
↓
GAP gates execution
↓
Checkpoints enforce review
The Plan attaches an authorized execution envelope to each task. This envelope contains:
- Execution: Local vs Cloud compute venue (Locality).
- Model: Which specific cognitive model is authorized.
- Checkpoints: Where human interruption is required.
GAP focuses on Gated Accountability. It records proposals and requires human approval for all state transitions. Active sandbox enforcement (VFS/ACLs) is currently archived.
Once the Plan is locked, GAP coordinates the agent.
To achieve massive throughput, GAP v3.0 introduces Ephemeral Worktree Isolation. When a Feature Plan is approved:
- Worktree Spawn: GAP provision a dedicated Git Worktree on a new feature branch (
feat/<name>). - Isolated Swarm: The authorized models (assigned in the Plan) execute the implementation exclusively within that worktree.
- Human Integration: The supervisor reviews the worktree output before it is ever merged into the primary developmental branch.
| Problem | How GAP Solves It |
|---|---|
| Agents drift from requirements over long contexts | Gated checkpoints re-anchor intent at every phase |
| No way to know what the agent decided vs what you approved | Immutable Ledger tracks every state transition |
| Agents "hallucinate" their own execution policies | Deterministic Audit Trail — policy is code and ledger, not prompts |
| No traceability from code back to intent | Chain of Custody links every task to a requirement |
| Deterministic (Protocol) | Probabilistic (Agent) | |
|---|---|---|
| Who | GAP | The LLM |
| What | Gates, checkpoints, policy | Requirements, design, code |
| Trust model | Absolute — defined in code | Gated — proposed, then approved |
Authority is never generated by an LLM. It is enforced by the protocol.
gap check status— View current state of all phases and gatesgap scribe create— Generate artifacts for any phasegap gate list / approve— Manage gate approvals with ACL extractiongap check traceability— Verify chain of custody from requirements → tasksgap checkpoint verify/approve— Runtime checkpoint enforcement- Manifest System — YAML workflow definition with protocol inheritance
- Ledger System — Immutable record of approvals and state transitions
- Task/Plan Separation — Distinguishing necessity (Tasks) from permission (Plan)
- Execution Envelopes — ACL, locality, model assignment, checkpoints in Plan
- Enhanced Gate System — Plan construction during task approval
- Structured Task Model — YAML tasks with traceability and references
The current focus: Complete separation of Tasks from Plan with explicit execution envelopes.
- Task Model — Structured YAML tasks with traceability to design/requirements
- Plan Construction — Supervisor-defined execution envelopes per task
- Execution Envelopes — Venue and model assignment in unified Plan file
- Manual Authority Phase — Supervisor defines all execution parameters
- Active Enforcement (ARCHIVED) — Deterministic ACL adherence logic is moved to archive.
# Coming: Plan envelope in .gap/plan.yaml
plan:
T-1:
cognition:
venue: local
model: qwen3-coder-next
checkpoints:
- after_implementation
- before_merge- Enhanced Gate System —
gap gate approve --edit-envelopefor Plan construction - Plan Management CLI —
gap plan show/edit/validatecommands - Checkpoint Enforcement — Runtime pause at declared boundaries
- Ledger Enhancement — Record Plan approvals with execution parameters
- Real-world Effectiveness Assessment — Empirical validation of security layers (VFS, ACLs, Gating) to ensure they provide actual protection beyond "Gated Security Theater."
- Red Teaming — Stress-testing the protocol against autonomous agents attempting to bypass the supervisor.
- Verification Efficacy — Tracking the signal-to-noise ratio of automated verification hooks.
- Model Control Layer — Explicit model assignment without orchestration
- Session Model — Law & Exception governance patterns
- Protocol Templates — Domain-specific workflow patterns
Ascent is a real-world project built with GAP governance. It's a capability resolver for learning — given a goal and a learner's verified state, it computes the minimal transformation required and delivers only the learning needed to close that gap.
Ascent is not a chat interface. It's a structured system with its own engine, knowledge graphs, and evidence models — exactly the kind of project where uncontrolled agent behavior would cause structural failures. GAP provides the guardrails.
Ascent demonstrates how GAP works in practice: requirements define learning goals, design maps the capability graph, tasks decompose into module generation, and execution is checkpointed to prevent drift.
pip install git+https://github.com/samir-alsayad/gated-agent-protocol.git@v1.0.0gap --help# Check current state
gap check status manifest.yaml
# Create a proposal for requirements
gap scribe create requirements --manifest manifest.yaml
# Review and approve
gap gate list --manifest manifest.yaml
gap gate approve requirements --manifest manifest.yamlOutput:
🟢 requirements: UNLOCKED
🔒 design: LOCKED (waiting for: requirements)
🔒 implementation: LOCKED (waiting for: design)
| Document | Description |
|---|---|
| Whitepaper | The full theory and architecture |
| Protocol Schema | How to define protocols |
| Project Schema | How to configure projects |
| CLI Reference | All commands |
| Integration Guide | Adding GAP to your tools |
| Model Control Layer | Upcoming MCL requirements and design |
- Python 3.10+
- macOS, Linux, or Windows
- No external services required (YAML/File-based Ledger)
git clone https://github.com/samir-alsayad/gated-agent-protocol.git
cd gated-agent-protocol
python -m venv .venv
source .venv/bin/activate
pip install -e .
pytest tests/ -vWe welcome contributions! See CONTRIBUTING.md.
See SECURITY.md for reporting vulnerabilities.
Open Standard — v1.0.0 — 2026 Created by Samir Alsayad.