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
    No fields configured for issues without a type.

    Projects

    Status

    Done

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions