feat: add SOD examples, DUTIES.md files, and README documentation

README.md

@@ -18,7 +18,7 @@ Every AI framework has its own structure. There's no universal, portable way to
 
 - **Git-native** — Version control, branching, diffing, and collaboration built in
 - **Framework-agnostic** — Export to any framework with adapters
-- **Compliance-ready** — First-class support for FINRA, Federal Reserve, and SEC regulatory requirements
+- **Compliance-ready** — First-class support for FINRA, Federal Reserve, SEC, and segregation of duties
 - **Composable** — Agents can extend, depend on, and delegate to other agents
 
 ## The Standard
@@ -34,6 +34,7 @@ my-agent/
 │
 │   # ── Behavior & Rules ──────────────────────────────────
 ├── RULES.md                # Hard constraints, must-always/must-never, safety boundaries
+├── DUTIES.md               # Segregation of duties policy and role boundaries
 ├── AGENTS.md               # Framework-agnostic fallback instructions
 │
 │   # ── Capabilities ──────────────────────────────────────
@@ -58,7 +59,8 @@ my-agent/
 ├── agents/                 # Sub-agent definitions (recursive structure)
 │   └── fact-checker/
 │       ├── agent.yaml
-│       └── SOUL.md
+│       ├── SOUL.md
+│       └── DUTIES.md       # This agent's role, permissions, boundaries
 ├── examples/               # Calibration interactions (few-shot)
 │
 │   # ── Runtime ───────────────────────────────────────────
@@ -76,6 +78,31 @@ When an agent learns a new skill or writes to memory, it opens a branch + PR for
 
 <img src="patterns/human-in-the-loop.png" alt="Human-in-the-Loop" width="600" />
 
+### Segregation of Duties (SOD)
+No single agent should control a critical process end-to-end. Define roles (`maker`, `checker`, `executor`, `auditor`), a conflict matrix (which roles can't be the same agent), and handoff workflows — all in `agent.yaml` + `DUTIES.md`. The validator catches violations before deployment.
+
+```yaml
+compliance:
+  segregation_of_duties:
+    roles:
+      - id: maker
+        description: Creates proposals
+        permissions: [create, submit]
+      - id: checker
+        description: Reviews and approves
+        permissions: [review, approve, reject]
+    conflicts:
+      - [maker, checker]         # maker cannot approve own work
+    assignments:
+      loan-originator: [maker]
+      credit-reviewer: [checker]
+    handoffs:
+      - action: credit_decision
+        required_roles: [maker, checker]
+        approval_required: true
+    enforcement: strict
+```
+
 ### Live Agent Memory
 The `memory/` folder holds a `runtime/` subfolder where agents write live knowledge — `dailylog.md`, `key-decisions.md`, and `context.md` — persisting state across sessions.
 
@@ -183,6 +210,18 @@ compliance:
   model_risk:
     validation_cadence: quarterly
     ongoing_monitoring: true
+  segregation_of_duties:
+    roles:
+      - id: analyst
+        permissions: [create, submit]
+      - id: reviewer
+        permissions: [review, approve, reject]
+    conflicts:
+      - [analyst, reviewer]
+    assignments:
+      compliance-analyst: [analyst]
+      fact-checker: [reviewer]
+    enforcement: strict
 ```
 
 ## CLI Commands
@@ -218,6 +257,16 @@ gitagent has first-class support for financial regulatory compliance:
 - **Reg S-P** — Customer privacy, PII handling
 - **CFPB Circular 2022-03** — Explainable adverse action, Less Discriminatory Alternative search
 
+### Segregation of Duties
+- **Roles & Permissions** — Define maker, checker, executor, auditor roles with controlled permissions
+- **Conflict Matrix** — Declare which role pairs cannot be held by the same agent
+- **Handoff Workflows** — Require multi-agent participation for critical actions (credit decisions, regulatory filings)
+- **Isolation** — Full state and credential segregation between roles
+- **DUTIES.md** — Root-level policy + per-agent role declarations
+- **Enforcement** — Strict (blocks deployment) or advisory (warnings only)
+
+Inspired by [Salient AI](https://www.trysalient.com/)'s purpose-built agent architecture and the [FINOS AI Governance Framework](https://air-governance-framework.finos.org/mitigations/mi-22_multi-agent-isolation-and-segmentation.html).
+
 Run `gitagent audit` for a full compliance checklist against your agent configuration.
 
 ## Adapters
@@ -264,7 +313,7 @@ See the `examples/` directory:
 
 - **`examples/minimal/`** — 2-file hello world (agent.yaml + SOUL.md)
 - **`examples/standard/`** — Code review agent with skills, tools, and rules
-- **`examples/full/`** — Production compliance agent with all directories, hooks, workflows, sub-agents, and regulatory artifacts
+- **`examples/full/`** — Production compliance agent with all directories, hooks, workflows, sub-agents, SOD with DUTIES.md, and regulatory artifacts
 - **`examples/gitagent-helper/`** — Helper agent that assists with creating gitagent definitions
 - **`examples/lyzr-agent/`** — Example Lyzr Studio integration
 

examples/full/DUTIES.md

@@ -0,0 +1,40 @@
+# Duties
+
+System-wide segregation of duties policy for the compliance-analyst agent system.
+
+## Roles
+
+| Role | Agent | Permissions | Description |
+|------|-------|-------------|-------------|
+| Analyst | compliance-analyst | create, submit | Performs regulatory analysis, generates findings and reports |
+| Reviewer | fact-checker | review, approve, reject | Reviews analysis for accuracy, verifies claims against authoritative sources |
+| Auditor | (unassigned) | audit, report | Audits completed reviews and maintains the compliance trail |
+
+## Conflict Matrix
+
+No single agent may hold both roles in any pair:
+
+- **Analyst <-> Reviewer** — The agent that produces findings cannot approve them
+- **Analyst <-> Auditor** — The agent that produces findings cannot audit them
+- **Reviewer <-> Auditor** — The agent that approves findings cannot audit the approval
+
+## Handoff Workflows
+
+### Regulatory Filing
+1. **Analyst** creates the filing draft and submits for review
+2. **Reviewer** verifies accuracy against authoritative sources, approves or rejects
+3. Approval required at each step before proceeding
+
+### Customer Communication
+1. **Analyst** drafts the communication
+2. **Reviewer** checks for FINRA 2210 compliance (fair, balanced, no misleading statements)
+3. Approval required before any communication is sent
+
+## Isolation Policy
+
+- **State isolation: full** — Each agent operates with its own memory and state. No agent may read or modify another agent's working memory.
+- **Credential segregation: separate** — Each role has its own credential scope. The analyst's data access credentials are distinct from the reviewer's.
+
+## Enforcement
+
+Enforcement mode is **strict**. Any SOD violation (e.g., assigning conflicting roles to the same agent) will fail validation and block deployment.

examples/full/agent.yaml

@@ -96,6 +96,42 @@ compliance:
     soc_report_required: true
     vendor_ai_notification: true
     subcontractor_assessment: true
+  segregation_of_duties:
+    roles:
+      - id: analyst
+        description: Performs regulatory analysis and generates findings
+        permissions:
+          - create
+          - submit
+      - id: reviewer
+        description: Reviews analysis for accuracy and completeness
+        permissions:
+          - review
+          - approve
+          - reject
+      - id: auditor
+        description: Audits completed reviews and maintains compliance trail
+        permissions:
+          - audit
+          - report
+    conflicts:
+      - [analyst, reviewer]
+      - [analyst, auditor]
+      - [reviewer, auditor]
+    assignments:
+      compliance-analyst: [analyst]
+      fact-checker: [reviewer]
+    isolation:
+      state: full
+      credentials: separate
+    handoffs:
+      - action: regulatory_filing
+        required_roles: [analyst, reviewer]
+        approval_required: true
+      - action: customer_communication
+        required_roles: [analyst, reviewer]
+        approval_required: true
+    enforcement: strict
 tags:
   - compliance
   - financial-services

examples/full/agents/fact-checker/DUTIES.md

@@ -0,0 +1,36 @@
+# Duties
+
+## Role
+
+**Reviewer** — Reviews analysis for accuracy and completeness.
+
+## Permissions
+
+- **review** — Examine outputs produced by the analyst
+- **approve** — Approve findings that meet accuracy and compliance standards
+- **reject** — Reject findings that are inaccurate, incomplete, or non-compliant
+
+## Boundaries
+
+### Must
+- Verify all factual claims against authoritative regulatory sources before approving
+- Reject any finding that cannot be independently verified
+- Document the basis for every approval or rejection decision
+
+### Must Not
+- Create original analysis or findings (analyst role only)
+- Modify the analyst's work — only approve or reject
+- Access the analyst's working state or memory
+- Use credentials assigned to other roles
+- Audit own review decisions (auditor role only)
+
+## Handoff Participation
+
+| Action | Position in Chain | Receives From | Hands Off To |
+|--------|------------------|---------------|--------------|
+| regulatory_filing | Step 2 | analyst | (terminal — approved or rejected) |
+| customer_communication | Step 2 | analyst | (terminal — approved or rejected) |
+
+## Isolation
+
+This agent operates under **full state isolation** with **separate credentials**. It cannot access the compliance-analyst's memory, state, or data access tokens.

examples/full/compliance/regulatory-map.yaml

@@ -77,3 +77,26 @@ mappings:
         controls:
           - vendor_supervisory_procedures
           - vendor_ai_change_notification
+
+  - capability: duty_segregation
+    rules:
+      - id: finos-ai-governance
+        name: "FINOS AI Governance — Multi-Agent Isolation"
+        controls:
+          - role_definition
+          - conflict_matrix_enforcement
+          - assignment_validation
+          - state_isolation
+          - credential_segregation
+      - id: finra-3110-sod
+        name: "FINRA Rule 3110 — Supervisory Separation"
+        controls:
+          - maker_checker_separation
+          - approval_workflow_enforcement
+          - independent_review_requirement
+      - id: soc2-logical-access
+        name: "SOC 2 — Logical Access Controls"
+        controls:
+          - role_based_access_control
+          - credential_isolation
+          - cross_boundary_approval

spec/SPECIFICATION.md

@@ -9,7 +9,7 @@
 The standard is designed to be:
 - **Framework-agnostic** — works with Claude Code, OpenAI, LangChain, CrewAI, AutoGen, and others
 - **Git-native** — version control, branching, diffing, and collaboration built in
-- **Compliance-ready** — first-class support for FINRA, Federal Reserve, and interagency regulatory requirements
+- **Compliance-ready** — first-class support for FINRA, Federal Reserve, interagency regulatory requirements, and segregation of duties
 - **Composable** — agents can extend, depend on, and delegate to other agents
 
 ## 2. Directory Structure
@@ -19,6 +19,7 @@ my-agent/
 ├── agent.yaml              # [REQUIRED] Agent manifest
 ├── SOUL.md                 # [REQUIRED] Identity and personality
 ├── RULES.md                # Hard constraints and boundaries
+├── DUTIES.md                 # Segregation of duties policy and role declaration
 ├── AGENTS.md               # Framework-agnostic fallback instructions
 ├── README.md               # Human documentation
 ├── skills/                 # Reusable capability modules
@@ -194,6 +195,48 @@ compliance:
     soc_report_required: false        # SOC 2 report required
     vendor_ai_notification: true      # Vendor must notify of AI changes
     subcontractor_assessment: false   # Fourth-party risk assessed
+
+  # Segregation of duties (multi-agent duty separation)
+  segregation_of_duties:
+    roles:                                   # Define roles for agents (min 2)
+      - id: maker                            # Initiates/creates
+        description: Creates proposals and initiates actions
+        permissions: [create, submit]
+      - id: checker                          # Reviews/approves
+        description: Reviews and approves maker outputs
+        permissions: [review, approve, reject]
+      - id: executor                         # Executes approved work
+        description: Executes approved actions
+        permissions: [execute]
+      - id: auditor                          # Audits completed work
+        description: Reviews completed actions for compliance
+        permissions: [audit, report]
+
+    conflicts:                               # SOD conflict matrix
+      - [maker, checker]                     # Maker cannot approve own work
+      - [maker, auditor]                     # Maker cannot audit own work
+      - [executor, checker]                  # Executor cannot approve what they execute
+      - [executor, auditor]                  # Executor cannot audit own execution
+
+    assignments:                             # Bind roles to agents
+      loan-originator: [maker]
+      credit-reviewer: [checker]
+      loan-processor: [executor]
+      compliance-auditor: [auditor]
+
+    isolation:
+      state: full                            # full | shared | none
+      credentials: separate                  # separate | shared
+
+    handoffs:                                # Critical actions requiring multi-role handoff
+      - action: credit_decision
+        required_roles: [maker, checker]
+        approval_required: true
+      - action: loan_disbursement
+        required_roles: [maker, checker, executor]
+        approval_required: true
+
+    enforcement: strict                      # strict | advisory
 ```
 
 ### Example Minimal agent.yaml
@@ -365,6 +408,30 @@ For regulated agents, RULES.md should include explicit regulatory constraints:
 - Never transmit restricted data across jurisdictional boundaries
 ```
 
+## 5a. DUTIES.md — Segregation of Duties
+
+Declares the agent's duties, role boundaries, and the system-wide SOD policy. DUTIES.md exists at two levels:
+
+**Root level** (`DUTIES.md`) — Documents the system-wide segregation of duties policy: all roles, the conflict matrix, handoff workflows, isolation policy, and enforcement mode. This is the SOD equivalent of `RULES.md` — it defines the policy that all agents in the system must follow.
+
+**Per-agent level** (`agents/<name>/DUTIES.md`) — Declares this specific agent's role, permissions, boundaries, and handoff participation. Each sub-agent's DUTIES.md answers: what is my role, what can I do, what must I not do, and who do I hand off to.
+
+### Root DUTIES.md Recommended Sections
+
+- **Roles** — Table of all roles, assigned agents, and permissions
+- **Conflict Matrix** — Which role pairs cannot be held by the same agent
+- **Handoff Workflows** — Step-by-step handoff chains for critical actions
+- **Isolation Policy** — State and credential isolation levels
+- **Enforcement** — Strict vs advisory mode
+
+### Per-Agent DUTIES.md Recommended Sections
+
+- **Role** — This agent's assigned role
+- **Permissions** — What actions this agent can take
+- **Boundaries** — Must/must-not rules specific to this role
+- **Handoff Participation** — Where this agent sits in handoff chains
+- **Isolation** — This agent's isolation constraints
+
 ## 6. AGENTS.md — Framework-Agnostic Instructions
 
 Provides fallback instructions compatible with Cursor, Copilot, and other tools that read `AGENTS.md`. This file supplements `agent.yaml` + `SOUL.md` for systems that don't understand the gitagent format.
@@ -864,6 +931,13 @@ A valid gitagent repository must:
 5. All referenced tools must exist in `tools/`
 6. All referenced sub-agents must exist in `agents/`
 7. `hooks.yaml` scripts must exist at specified paths
+8. If `compliance.segregation_of_duties` is present:
+   - `roles` must define at least 2 roles with unique IDs
+   - `conflicts` pairs must reference defined role IDs
+   - `assignments` must reference defined role IDs
+   - No agent in `assignments` may hold roles that appear together in `conflicts`
+   - `handoffs.required_roles` must reference defined role IDs and include at least 2
+   - Assigned agents should exist in the `agents` section
 
 ## 19. CLI Commands
 
@@ -942,6 +1016,15 @@ All schemas are in `spec/schemas/`:
 | SR 21-8 | BSA/AML Model Risk | `compliance.model_risk` for AML agents |
 | CFPB Circular 2022-03 | Adverse Action + AI | `compliance.data_governance.lda_search` |
 
+### Segregation of Duties References
+
+| Document | Subject | gitagent Impact |
+|----------|---------|-----------------|
+| FINOS AI Governance Framework | Multi-Agent Isolation & Segmentation | `compliance.segregation_of_duties` |
+| SOC 2 Type II | Logical Access Controls | `segregation_of_duties.isolation` |
+| SR 11-7 Section IV | Independent Review | `segregation_of_duties.conflicts` (maker/checker separation) |
+| FINRA 3110 | Supervisory Systems (duty separation) | `segregation_of_duties.handoffs` |
+
 ---
 
 *This specification is a living document. Contributions welcome.*