Skip to content

docs: update enterprise-governance docs and fix risk_tier vocabulary mismatch in agentv-governance skill #1182

@christso

Description

@christso

Context

Three gaps surfaced after #1178 / #1179 / #1180 (the governance skill + core slim + compliance-lint Action):


Gap 1 — Dead link in enterprise-governance.mdx

apps/web/src/content/docs/docs/guides/enterprise-governance.mdx line 141:

[governance metadata]: ./agent-eval-layers/

agent-eval-layers.mdx contains zero governance content. The link is stale — this was probably written as a forward reference that never materialised. Fix: either make that section self-contained or point at a real anchor.


Gap 2 — risk_tier vocabulary mismatch

plugins/agentv-dev/skills/agentv-governance/references/eu-ai-act-risk-tiers.md (and lint-rules.md) use:

prohibited | high_risk | limited_risk | minimal_risk

But the existing red-team suites (examples/red-team/suites/*.eval.yaml) and enterprise-governance.mdx both use the shorter form:

prohibited | high | limited | minimal

This is what the old validator enforced before #1179 removed it. The skill currently lints against the wrong vocabulary — any existing eval with risk_tier: high would get a false violation.

Recommended fix: align the skill to high | limited | minimal (matching shipped examples). Update both eu-ai-act-risk-tiers.md and the allowed-values table in lint-rules.md (Rule 6). No example files need to change.


Gap 3 — eval-level governance block undocumented on agentv.dev

No page on the docs site explains:

  • The governance: block in *.eval.yaml files (YAML shape, merge semantics, which fields are valid)
  • The agentv-governance skill and when to load it
  • The examples/governance/compliance-lint/ reference Action

enterprise-governance.mdx mentions "eval-level governance schema" but never shows the YAML shape. The canonical shape is in plugins/agentv-dev/skills/agentv-governance/references/governance-yaml-shape.md — that content (or a summary of it) belongs on agentv.dev.


Acceptance signals

  • Dead link in enterprise-governance.mdx fixed
  • eu-ai-act-risk-tiers.md and lint-rules.md in the skill use high | limited | minimal
  • enterprise-governance.mdx (or a linked page) documents the eval-level governance: block shape
  • agentv-governance skill and compliance-lint Action mentioned in docs (a single paragraph with a link to examples/governance/compliance-lint/README.md is sufficient)
  • bun run validate:examples passes (no regressions in existing red-team evals)

Non-goals

  • No need to update the existing red-team example files — they already use the correct short-form vocabulary.
  • No need to add a full reference page for the Action; the README in examples/ is the canonical doc.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    Status

    In progress

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions