# Governance

Governance controls how much oversight is applied to agent decisions. It adds structured checkpoints without slowing down simple tasks.

## Three governance levels

| Level   | When to use                                         | Overhead                                      |
|---------|----------------------------------------------------|-----------------------------------------------|
| **none**     | Solo developer, prototyping, hackathons               | No checkpoints                                |
| **standard** | Small teams, startups, normal development             | Decision gates at key transitions             |
| **strict**   | Enterprise, regulated industries, production systems  | Full audit trail, RBAC, NIST mapping          |

## Configuration

```
governance: standard  # none | standard | strict
```

## Level: none (default)

No governance overhead. Agents work freely. Suitable for:

- Personal projects
- Prototyping
- Hackathons
- Trusted solo development

## Level: standard

Adds structured decision gates based on task complexity.

### Decision gates

| Complexity | Gate                  | Action                                                |
|------------|-----------------------|------------------------------------------------------|
| TRIVIAL    | None                  | Agent acts autonomously                               |
| MODERATE   | Deliverable review     | Produce deliverable, user validates before next step |
| COMPLEX    | Phased approval       | spec.md, plan.md, tasks.md — each requires approval  |

### Risk assessment

Before executing a workflow, Jarvis assesses risk:

| Risk   | Workflows                             | Controls                                                   |
|--------|--------------------------------------|------------------------------------------------------------|
| LOW    | `/bugfix`, `/review`, `/docs`       | Agent acts, summary post-action                            |
| MEDIUM | `/feature`, `/sprint`, `/refactor`  | Plan required, user validates                              |
| HIGH   | `/release`, `/hotfix`, `/mvp`, `/upgrade` | Risk assessment + rollback plan + approval               |

For HIGH risk workflows, Jarvis produces `risk-assessment.md` with:

- Identified risks and their probability
- Impact assessment for each risk
- Mitigation strategies
- Rollback plan

### Quality checkpoints

At the end of every COMPLEX workflow (4+ steps), Jarvis produces `_quality.md`:

- **Delivered**: list of all produced deliverables
- **Validated**: what was reviewed and approved by the user
- **Risks remaining**: open risks, known limitations, tech debt introduced
- **Lessons learned**: what worked well, what should improve
- **Metrics**: lead time, steps executed, agents involved

## Level: strict

Everything in standard, plus:

### Audit trail

Every agent action is logged in `_audit.md`:

```
## Audit Trail

| Timestamp            | Agent            | Action            | Decision  | Rationale                          |
|---------------------|------------------|-------------------|----------|------------------------------------|
| 2026-03-21T10:00:00Z | @professor-x     | Write spec        | APPROVED  | User validated requirements         |
| 2026-03-21T10:15:00Z | @tony-stark      | Architecture decision: PostgreSQL | APPROVED | Matches team expertise   |
```

### Role-based access control (RBAC)

Sensitive agents require explicit authorization:

| Agent               | Sensitivity | Requires                    |
|---------------------|-------------|-----------------------------|
| `@punisher`         | HIGH        | Security clearance           |
| `@microchip`       | CRITICAL    | Red team authorization        |
| `@doctor-doom`     | HIGH        | Explicit invocation only      |
| `@thor`            | MEDIUM      | Deploy authorization          |

### NIST AI RMF mapping

For regulated industries, strict governance maps agent decisions to NIST AI Risk Management Framework categories:

- **Govern**: Policies and accountability for AI decisions
- **Map**: Context and risk identification
- **Measure**: Metrics and monitoring
- **Manage**: Risk mitigation and response

## Combining with YOLO mode

Governance and YOLO are complementary controls:

- **YOLO** controls _speed_ — how much agents ask before acting
- **Governance** controls _oversight_ — what checkpoints are required

They work together:

```
# Fast within phases, structured transitions

yolo: true

governance: standard
```

With this configuration, agents execute autonomously within each workflow phase, but formal decision gates still apply between phases (spec, plan, tasks, implement).

## Choosing a governance level

| Your situation                          | Recommendation                        |
|-----------------------------------------|--------------------------------------|
| Solo developer, prototyping             | `governance: none`                   |
| Small team, normal development          | `governance: standard`               |
| Enterprise, regulated industry          | `governance: strict`                 |
| Open-source project                     | `governance: standard`               |
| Production deployment                   | `governance: standard` or `strict`   |