# HEALTH.md - HEALTH Subsystem (Embedded)
**Authority:** subsystem (REAL)
**Layer:** Operational
**Binding:** No
This document defines the health subsystem, which manages proof-based health claims and system autonomy assessment.
## CLI Surface
```bash
decapod govern health <subcommand>
```
### Subcommands
#### Core Health Claims
- **`add --claim <claim> --proof <proof>`** - Record a new health claim with proof
- **`get --claim <claim>`** - Retrieve health claim state and proof history
- **`list`** - List all health claims with their states
#### System Monitoring (Consolidated)
- **`summary`** - System health overview (formerly `decapod heartbeat`)
- Aggregates health claim states (VERIFIED, STALE, CONTRADICTED, ASSERTED)
- Shows pending policy approvals
- Reports watcher staleness status
- Lists system alerts
- **`autonomy [--id <agent>]`** - Agent autonomy tier assessment (formerly `decapod trust status`)
- Computes autonomy tier (Tier0/Tier1/Tier2) from proof history
- Shows success/failure counts from health claims
- Provides reasoning for tier assignment
- Validates actor against audit log
## Health States
Health claims progress through states based on proof verification:
- **ASSERTED** - Claim recorded but not yet verified
- **VERIFIED** - Proof executed successfully, claim confirmed
- **STALE** - Proof hasn't run recently (needs re-verification)
- **CONTRADICTED** - Proof execution failed, claim invalidated
## Subsystem Consolidation
As of v0.3.0, the health subsystem has absorbed:
1. **Heartbeat functionality** (`summary` subcommand)
- Was: `decapod heartbeat`
- Now: `decapod govern health summary`
- Reason: Heartbeat was a thin aggregator over health/policy/watcher data
2. **Trust functionality** (`autonomy` subcommand)
- Was: `decapod trust status --id <agent>`
- Now: `decapod govern health autonomy --id <agent>`
- Reason: Trust was computed entirely from health claim states
This consolidation:
- Reduces top-level CLI clutter (22 → 9 commands)
- Groups governance/monitoring commands together
- Makes relationships between subsystems explicit
- Maintains all functionality without changes
## Storage
Health claims are stored in SQLite:
- Database: `health.db` (in state directory)
- Schema: `(claim TEXT PRIMARY KEY, state TEXT, ts INTEGER, proof TEXT)`
## See Also
- `POLICY.md` - Policy approval system (risk classification)
- `WATCHER.md` - Integrity monitoring (staleness detection)
- `HEARTBEAT.md` - Deprecated, now `summary` subcommand
- `TRUST.md` - Deprecated, now `autonomy` subcommand
- `specs/SYSTEM.md` - Authority and proof doctrine