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

patel-lyzr · patel-lyzr · commit 877c6efb869b · 2026-02-27T21:08:20.000+05:30
- examples/full/agent.yaml: segregation_of_duties config with analyst,
  reviewer, and auditor roles
- examples/full/DUTIES.md: root-level SOD policy (roles, conflicts,
  handoffs, isolation, enforcement)
- examples/full/agents/fact-checker/DUTIES.md: per-agent role declaration
- examples/full/compliance/regulatory-map.yaml: duty_segregation mapping
- README.md: SOD pattern section, updated directory tree, compliance docs

Part 4 of 4 — depends on feat/sod-3-adapters
diff --git a/README.md b/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
 
diff --git a/examples/full/DUTIES.md b/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.
diff --git a/examples/full/agent.yaml b/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
diff --git a/examples/full/agents/fact-checker/DUTIES.md b/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.
diff --git a/examples/full/compliance/regulatory-map.yaml b/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
