| name | governance-observability |
| description | Use when defining governance metrics, reading governance health snapshots, generating the governance dashboard, or understanding the governance data model. Referenced by the governance-auditor agent and the /governance-health command. |
Governance Observability
Defines the metrics, snapshot formats, and dashboard specifications
for governance health. This skill is referenced by:
- The
governance-auditor agent when producing audit reports
- The
/governance-health command when displaying results
- The
/governance-audit command when updating snapshots
- The portfolio dashboard when aggregating governance data
Governance Metrics Catalogue
| Metric | Type | Description |
|---|
| Total constraints | integer | Total governance constraints in HARNESS.md |
| Falsifiability ratio | percentage | Proportion of governance constraints scored as "falsifiable" |
| Falsifiable | integer | Number of constraints rated "Falsifiable" |
| Vague | integer | Number of constraints rated "Vague" |
| Semantic drift stage | integer (1-5) | Numeric semantic drift severity from the five-stage model |
| Drift velocity | enum (stable/increasing/decreasing) | Direction of drift trend between audits |
| Governance debt items | integer | Number of governance debt items identified |
| Aggregate debt score | integer | Sum of (severity x blast_radius) across all debt items |
| Frame alignment score | percentage | Proportion of governance constraints with confirmed three-frame alignment |
Snapshot Format Extension
Governance metrics are expressed as a markdown section in audit
reports. The governance-auditor includes a Governance Summary section
that agents (including the snapshot generator) can parse directly:
## Governance Summary
- Total constraints: 4
- Falsifiable: 3 (with verification criteria)
- Vague: 0 (lacking operational meaning)
- Falsifiability ratio: 75%
- Semantic drift stage: 1/5
- Drift velocity: stable
- Governance debt items: 2
- Aggregate debt score: 8 (sum of severity x blast radius)
- Frame alignment score: 50%
Staleness Thresholds
| Metric | Fresh | Stale | Critical |
|---|
last_audit | < 90 days | 90-180 days | > 180 days |
drift_velocity | stable or decreasing | increasing for 1 quarter | increasing for 2+ quarters |
falsifiability_ratio | > 0.75 | 0.50-0.75 | < 0.50 |
debt_inventory_size | 0-2 items | 3-5 items | > 5 items |
Audit Report Format
Governance audit reports are written to
observability/governance/audit-YYYY-MM-DD.md by the
governance-auditor agent. Each report contains:
- Summary — overall governance health score, counts, ratios
- Constraint Assessment — per-constraint table with
falsifiability score, drift risk, frame alignment, drift stage
- Governance Debt Inventory — per-item table with severity,
blast radius, score, affected constraints, recommendation
- Debt Cycle Analysis — any reinforcement patterns detected
- Prioritised Recommendations — ordered by debt score
Dashboard Specification
See references/dashboard-spec.md for the full HTML dashboard
specification — sections, data sources, visualisation types, and
colour schemes.
Portfolio Integration
When governance data is aggregated across repos (via
/portfolio-assess), the portfolio dashboard gains:
- A governance column in the repo table showing each repo's
falsifiability ratio and drift score
- A governance summary section with:
- Distribution of falsifiability ratios across repos
- Shared governance gaps (terms that are vague across multiple repos)
- Drift trend comparison across repos
- Aggregate debt inventory size
