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>"

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

# Show closed actions (resolved, dismissed, won't-fix)
curl "https://shoehorn.example.com/api/v1/governance/actions?closed=true" \
  -H "Authorization: Bearer <token>"

closed=true returns every closed action and can’t be combined with a filter that only matches active actions (status=open, status=in_progress, or actionable=true) — that pairing is rejected.

Updating Many Actions at Once

Move several actions to the same status in one request:

curl -X POST https://shoehorn.example.com/api/v1/governance/actions/bulk \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"ids": ["<id1>", "<id2>"], "status": "resolved"}'

The response reports how many actions changed ({"requested": 2, "updated": 2}). Actions already in a final state are left as-is and don’t count toward updated.

From the CLI:

shoehorn governance actions bulk <id1> <id2> --status resolved

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>"

Deleting Actions

Deleting a governance action removes it permanently. There’s no soft-delete or recovery, so delete only actions you no longer need to track.