Governance Workflow

SOMA's governance gate is the boundary between machine-generated knowledge (L3) and organizational truth (L4). By default, every L3 proposal requires explicit human review before it becomes a constraint that affects agent behavior. For mature vaults with high-quality evidence, opt-in auto-promotion is available.

Why Governance Matters

Auto-generated policies have blast radius across all agents. If the Synthesizer identifies "agents should always retry 3 times" from pattern data, but the business context says retries cause duplicate transactions, blind enforcement is harmful. The governance gate ensures a human reviews proposals before they become mandatory constraints.

The Promotion Pipeline

Agent traces  →  Harvester writes to L1
                       ↓
                Synthesizer detects patterns across L1
                       ↓
                Creates L3 proposals (confidence + evidence links)
                       ↓
                Human reviewer (CLI or Dashboard)
                       ↓
          promote() → L4 canon  |  reject() → stays in L3

L3 to L4 requires explicit human action by default. See Auto-Promotion for the opt-in alternative.

Step 1: List Pending Proposals

Start by seeing what the Synthesizer and Cartographer have proposed:

soma governance list

[soma] === Pending Governance Proposals ===

  ID                          Type        Confidence  Evidence
  retry-heavy-agents          archetype   0.82        14 traces from 6 agents
  fetch-data-dominance        insight     0.71        9 traces from 4 agents
  payload-size-limit          policy      0.55        5 traces from 1 agent
  stale-cache-pattern         insight     0.44        3 traces from 2 agents

  4 proposals pending review

Proposals are sorted by confidence descending. The Synthesizer scores proposals based on cross-agent corroboration (5+ agents scores 0.8+) and evidence count.

Step 2: Inspect a Proposal

Before making a decision, drill into the evidence:

soma governance show --id retry-heavy-agents

[soma] === Proposal: retry-heavy-agents ===

  Type:       archetype
  Layer:      L3 (emerging)
  Status:     pending
  Confidence: 0.82
  Created:    2026-03-20T14:32:09.000Z

  Summary:
    6 agents exhibit retry counts above threshold. Pattern suggests
    missing circuit breaker logic. Agents: alpha, beta, gamma, delta,
    epsilon, zeta.

  Evidence chain (14 entries):
    [L1] decision-retry-agent-alpha-exec-091  (retry count: 4, failed)
    [L1] decision-retry-agent-alpha-exec-088  (retry count: 3, completed)
    [L1] decision-retry-agent-beta-exec-044   (retry count: 5, failed)
    [L1] decision-retry-agent-gamma-exec-031  (retry count: 4, failed)
    ... (10 more)

Step 3: Evaluate — What to Look For

When reviewing a proposal, assess these dimensions:

Confidence Score

Range	Meaning	Guidance
0.8 - 1.0	Strong cross-agent pattern	Likely promote-worthy if business context supports it
0.5 - 0.8	Moderate signal	Needs careful evidence review
0.3 - 0.5	Weak / single-agent	Usually reject or wait for more data
< 0.3	Noise	Reject unless you have domain knowledge supporting it

Single-agent patterns are capped at 0.5 confidence regardless of evidence count. This is intentional — organizational truth requires cross-agent validation.

Agent Diversity

A proposal corroborated by 6 different agents is stronger than one backed by 600 traces from a single agent. Check:

• How many distinct agents contributed evidence?
• Are the agents independent, or do they share the same codebase?
• Do different agent types (fetchers, processors, orchestrators) see the same pattern?

Business Context

The Synthesizer has no business knowledge. You do. Ask:

• Does this pattern reflect good behavior or bad behavior?
• Would enforcing this as policy help or hurt?
• Are there edge cases where this pattern should not apply?
• Does this conflict with existing L4 canon?

Example: "agents always retry 3 times" might be a correct observation but a terrible policy if retries cause duplicate transactions in your domain.

Blast Radius

Policies promoted to L4 become mandatory constraints via the Policy Bridge. Consider:

• How many agents will this affect?
• Is the policy scoped narrowly enough?
• What happens if an agent violates it — error or warning?
• Can it be reversed easily if it causes problems?

Step 4: Promote or Reject

Promoting a Proposal

soma governance promote --id retry-heavy-agents

[soma] Promoting retry-heavy-agents to L4 canon...
[soma] Created L4 entry: canon-retry-heavy-agents
[soma]   ratified_by: cli-user
[soma]   ratified_at: 2026-03-21T09:15:00.000Z
[soma]   origin_l3_id: retry-heavy-agents
[soma] L3 entry marked as 'promoted'
[soma] Done. L4 now has 9 entries.

What happens on promote:

1. A new L4 entity is created with ratified_by, ratified_at, and origin_l3_id fields
2. The original L3 entry is marked status: promoted
3. The L3 entry no longer decays (promoted entries are preserved)
4. The Policy Bridge immediately serves the new L4 entry for enforce queries
5. Agents querying with enforce intent will see it on their next policy check

Rejecting a Proposal

soma governance reject --id stale-cache-pattern --reason "Insufficient evidence — only 2 agents, need broader validation"

[soma] Rejected stale-cache-pattern
[soma]   reason: "Insufficient evidence — only 2 agents, need broader validation"
[soma]   rejected_by: cli-user
[soma]   rejected_at: 2026-03-21T09:17:00.000Z
[soma] Entry will not decay.

What happens on reject:

1. The L3 entry is marked status: rejected with rejected_by, rejected_at, and rejection_reason
2. The entry no longer decays (rejected entries are preserved for audit)
3. The entry no longer appears in governance list output
4. Future Synthesizer runs will not re-propose the same pattern (dedup by evidence overlap)

Dashboard Alternative

The AgentFlow Dashboard provides a visual governance workflow at the /governance page:

• Pending proposals list with approve/reject buttons
• Evidence chain drill-down — expand any proposal to see linked L1 entries
• Canon section — view all ratified L4 entries with reviewer and timestamp
• Layer summary bar showing L1/L2/L3/L4 entry counts

The dashboard communicates with SOMA through the API endpoints. Mutations (promote/reject) are executed via the SOMA CLI internally, ensuring all write-path permissions are enforced. The browser never touches the vault directly.

See the Dashboard guide for setup and usage.

Auto-Promotion (Opt-In)

For mature vaults where manual review of every proposal is impractical, SOMA supports automatic promotion of high-confidence proposals. Auto-promotion is disabled by default and must be explicitly enabled.

Enabling Auto-Promotion

soma pipeline --governance-auto-promote

Or in soma watch mode, add the --governance-auto-promote flag.

Default Thresholds

Criterion	Default	Rationale
Confidence score	>= 0.9	Only strong cross-agent patterns qualify
Distinct agents	>= 5	Requires evidence from 5+ independent agents

Proposals below either threshold are skipped and remain in the manual review queue.

Auditability

Auto-promoted entries are distinguishable from human-reviewed ones:

• ratified_by: 'auto-promote' (vs. cli-user or a human reviewer ID)
• ratified_at timestamp records when promotion occurred

This lets operators filter and audit auto-promoted policies separately.

When to Use Auto-Promotion

Auto-promotion works well when:

• Your vault has many agents (10+) producing consistent evidence
• The review backlog is growing faster than human reviewers can process
• You trust the confidence scoring (validated by reviewing early proposals)

It is not recommended for new vaults with limited agent diversity, where patterns may be artifacts of a single agent's behavior.

Governance Rules

These rules are enforced at the API level and cannot be bypassed:

Rule	Error
Only L3 entries can be promoted	LayerPermissionError: only L3 entries eligible for promotion
L2 entries cannot be promoted	GovernanceError: L2 entries cannot be promoted
Already-promoted entries cannot be re-promoted	GovernanceError: entry already promoted
Already-rejected entries cannot be re-promoted	GovernanceError: entry already rejected
Only pending status entries are eligible	GovernanceError: entry status must be pending
L4 writes require Governance API	LayerPermissionError: only governance can write to L4

There is no "undo promote" operation. If an L4 entry needs to be deprecated, update its status to deprecated via the vault API. The evidence chain is preserved.