Governance

Governance in Shoehorn helps you define and enforce engineering standards across your organization. Track compliance, assign remediation actions, and monitor improvement over time.

Governance Actions

Actions are trackable items that represent work needed to meet engineering standards. They can be created manually or generated automatically from scorecards and security findings.

Action Properties

Field	Description
Title	What needs to be done
Entity	The service or component affected
Priority	critical, high, medium, low
Status	Current state (see workflow below)
Source	Where the action originated: scorecard, security, policy, or manual
Assigned To	Person responsible
Due Date	SLA deadline
Resolution Note	How it was resolved

Status Workflow

open  ──>  in_progress  ──>  resolved
  │            │               │
  │            │               └──>  open (reopen)
  │            │
  └──>  dismissed ──────────>  open (reopen)
  │
  └──>  wont_fix  ──────────>  open (reopen)

Creating Actions

Via the UI

1. Navigate to Governance > Actions
2. Click Create Action
3. Select the entity, set priority and title
4. Optionally assign and set a due date

Via the API

curl -X POST https://shoehorn.example.com/api/v1/governance/actions \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "entity_id": "<entity-uuid>",
    "title": "Add README documentation",
    "priority": "medium",
    "source_type": "policy",
    "sla_days": 30
  }'

Updating Actions

curl -X PATCH https://shoehorn.example.com/api/v1/governance/actions/<id> \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "resolved",
    "resolution_note": "Added comprehensive README with API examples"
  }'

Filtering Actions

# Filter by status and priority
curl "https://shoehorn.example.com/api/v1/governance/actions?status=open&priority=critical" \
  -H "Authorization: Bearer <token>"

# Filter overdue actions
curl "https://shoehorn.example.com/api/v1/governance/actions?overdue=true" \
  -H "Authorization: Bearer <token>"

# Filter by entity
curl "https://shoehorn.example.com/api/v1/governance/actions?entity_id=<uuid>" \
  -H "Authorization: Bearer <token>"

Governance Dashboard

Navigate to Governance > Dashboard for an organization-wide view:

Metric	Description
Health Score	Average scorecard score across all entities
Health Grade	Letter grade (A+ to F)
Open Actions	Count of unresolved actions
In Progress	Actions being worked on
Overdue	Actions past their due date
Resolved (30d)	Actions resolved in the last 30 days
Doc Coverage	Percentage of entities with README
Grade Distribution	Count of entities per grade

Documentation Health

Navigate to Governance > Documentation to track documentation coverage:

Metric	Description
Has README	Entity has a README file
Has Runbooks	Runbooks are defined
Has Changelog	Changelog path is set
Has API Docs	API interfaces are documented
Doc Score	Scorecard documentation category score
Freshness	How recently docs were updated

Filter by: missing README, no runbooks, stale documentation.

Entity-Specific Governance

View governance actions for a specific entity:

1. Navigate to the entity detail page
2. Click the Governance tab
3. See open actions, compliance status, and history

Or via API:

curl https://shoehorn.example.com/api/v1/entities/<id>/governance/actions \
  -H "Authorization: Bearer <token>"

Soft Deletes

Governance actions use soft deletes to maintain compliance history. Deleted actions are excluded from queries but retained in the database for audit purposes.