veritas-kanban/docs/SOP-delegation.md

SOP: Delegation Management

Purpose

Configure and manage task delegation — temporarily routing new task assignments to a designated delegate agent when the primary agent is unavailable, overloaded, or explicitly stepping back. Delegation includes scope, exclusions, and automatic expiry.

Prerequisites

• Veritas Kanban server running with admin API key configured
• Admin-level authentication (required for setting and revoking delegation)
• The delegate agent must be active and capable of handling delegated scope

Concepts

Term	Definition
Delegate agent	The agent that receives tasks during the delegation period
Expires	ISO timestamp when delegation automatically ends (must be in the future)
Scope	Which task categories are delegated: all, unassigned, or matching (specific criteria)
Exclude priorities	Task priorities that are NOT delegated (e.g., don't delegate critical tasks)
Exclude tags	Task tags that are NOT delegated

Step-by-Step: Set Up Delegation

1. Check current delegation status

curl -s http://localhost:3001/api/delegation

Returns { "delegation": null } if no delegation is active, or the current delegation object.

2. Configure delegation

Requires admin auth. Include your admin API key in the Authorization header.

curl -s -X POST http://localhost:3001/api/delegation \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <your-admin-key>' \
  -d '{
    "delegateAgent": "CASE",
    "expires": "2026-03-22T09:00:00Z",
    "scope": "all",
    "excludePriorities": ["critical"],
    "excludeTags": ["security", "production"],
    "createdBy": "brad"
  }'

Response:

{
  "delegation": {
    "id": "deleg_abc123",
    "delegateAgent": "CASE",
    "expires": "2026-03-22T09:00:00Z",
    "scope": "all",
    "excludePriorities": ["critical"],
    "excludeTags": ["security", "production"],
    "createdBy": "brad",
    "createdAt": "2026-03-21T17:00:00Z",
    "active": true
  }
}

Validation: If expires is in the past, the server returns 400 Validation Error: Expiry date must be in the future.

3. Verify delegation is active

curl -s http://localhost:3001/api/delegation | jq '.delegation.active'
# → true

4. Review the delegation log

# All delegation approvals
curl -s "http://localhost:3001/api/delegation/log"

# For a specific task
curl -s "http://localhost:3001/api/delegation/log?taskId=task_20260321_abc"

# For a specific agent
curl -s "http://localhost:3001/api/delegation/log?agent=CASE&limit=20"

Step-by-Step: Revoke Delegation

Revoke immediately before the scheduled expiry:

curl -s -X DELETE http://localhost:3001/api/delegation \
  -H 'Authorization: Bearer <your-admin-key>'

Response: { "success": true } on success. 404 if no active delegation exists.

Revocation is logged in the audit log automatically.

Scope Reference

Scope	Behavior
all	All new task assignments go to the delegate (minus exclusions)
unassigned	Only tasks with no assigned agent go to the delegate
matching	Only tasks matching specific criteria (configure in matchCriteria)

Exclusion Reference

Use exclusions to protect your most critical work from delegation:

{
  "excludePriorities": ["critical"],
  "excludeTags": ["security", "production", "pii"]
}

Tasks matching any exclusion bypass delegation and require direct handling (or remain unassigned until the primary agent is available).

Delegation Expiry

Delegation expires automatically at the expires timestamp. No action needed — the system reverts to normal assignment routing.

To check time remaining:

curl -s http://localhost:3001/api/delegation | jq '.delegation.expires'

Common Delegation Scenarios

Overnight coverage

# Delegate everything non-critical until morning
curl -s -X POST http://localhost:3001/api/delegation \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <key>' \
  -d '{
    "delegateAgent": "CASE",
    "expires": "2026-03-22T08:00:00Z",
    "scope": "all",
    "excludePriorities": ["critical"],
    "createdBy": "brad"
  }'

Focused work block (unassigned only)

# Only route unassigned tasks to CASE while primary handles an important task
curl -s -X POST http://localhost:3001/api/delegation \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <key>' \
  -d '{
    "delegateAgent": "CASE",
    "expires": "2026-03-21T19:00:00Z",
    "scope": "unassigned",
    "createdBy": "brad"
  }'

API Endpoints Used

Method	Path	Purpose
GET	/api/delegation	Get current delegation settings
POST	/api/delegation	Set (or replace) delegation — requires admin
DELETE	/api/delegation	Revoke delegation — requires admin
GET	/api/delegation/log	View delegation approval log

Common Issues / Troubleshooting

Issue	Cause	Fix
403 Forbidden on POST/DELETE	Using a non-admin API key	Switch to the admin key; check authorize('admin') config
400 Expiry date must be in the future	expires timestamp is in the past	Use a future timestamp; check server timezone if unsure
404 on DELETE	No active delegation to revoke	Verify with GET /api/delegation first
Delegation not routing tasks	scope or exclusions too restrictive	Review exclusion list; test with a low-priority, untagged task
Tasks going to wrong agent	Delegation expired	Check expires timestamp; re-set delegation if needed

Related Docs

• docs/features/delegation.md — Feature deep-dive
• SOP-agent-task-workflow.md — How delegation fits into the standard task workflow
• SOP-lifecycle-hooks.md — Hooks can fire on delegation events