feat(core): optional governance metadata on EvalMetadata and EvalTest (#1165)

Adds an optional `governance` block (OWASP LLM Top 10 / OWASP Agentic / MITRE
ATLAS / cross-framework controls / EU AI Act risk tier / owner) to suite-level
EvalMetadata and case-level EvalTest.metadata. The shape is permissive: every
field is optional, custom prefixes are first-class, and value validation is a
soft warning, never an error.

Existing evals without the block validate and run unchanged. Case-level blocks
merge with suite-level (arrays concat with dedupe, scalars override). Result
metadata is surfaced into the JSONL artifact so reports and `jq` pipelines can
aggregate by control.

Closes #1161

Author: christso

apps/cli/src/commands/eval/artifact-writer.ts

@@ -160,6 +160,8 @@ export interface IndexArtifactEntry {
   readonly output_path?: string;
   readonly input_path?: string;
   readonly response_path?: string;
+  /** Case-level metadata pass-through (governance taxonomies, skill tags, etc.). */
+  readonly metadata?: Record<string, unknown>;
 }
 
 export type ResultIndexArtifact = IndexArtifactEntry;
@@ -573,6 +575,7 @@ export function buildIndexArtifactEntry(
     input_path: options.inputPath
       ? toRelativeArtifactPath(options.outputDir, options.inputPath)
       : undefined,
+    metadata: result.metadata,
   };
 }
 
@@ -606,6 +609,7 @@ export function buildResultIndexArtifact(result: EvaluationResult): ResultIndexA
     response_path: hasResponse
       ? path.posix.join(artifactSubdir, 'outputs', 'response.md')
       : undefined,
+    metadata: result.metadata,
   };
 }
 

packages/core/src/evaluation/metadata.ts

@@ -1,12 +1,56 @@
 import { z } from 'zod';
 import type { JsonObject } from './types.js';
 
+/**
+ * Optional governance block on suite-level `EvalMetadata` and case-level `EvalTest.metadata`.
+ *
+ * The schema is intentionally permissive: every field is optional, unknown fields pass through,
+ * and value validation is delegated to a soft-warning lint in `eval-validator.ts`. The block
+ * captures convergence on public AI-governance taxonomies (NIST AI RMF, ISO/IEC 42001, EU AI Act,
+ * OWASP LLM Top 10, MITRE ATLAS) without prescribing a workflow or hard-coding ID lists.
+ *
+ * Versioning lives in field names (`owasp_llm_top_10_2025`) so that when a standard revises and
+ * redefines IDs (OWASP LLM Top 10 v2025 vs v1.1), agentv ships a new field rather than
+ * silently changing the meaning of existing tags.
+ *
+ * To extend with a new versioned taxonomy: add an optional `string[]` field here, document it in
+ * the README under examples/red-team/, and propagate through the `agentv eval` JSONL output.
+ */
+const GovernanceMetadataSchema = z
+  .object({
+    /** Schema version of this governance block itself (lets the block evolve). */
+    schema_version: z.string().optional(),
+    /** OWASP LLM Top 10 v2025 IDs (LLM01..LLM10). */
+    owasp_llm_top_10_2025: z.array(z.string()).optional(),
+    /** OWASP Top 10 for Agentic Applications v2025 (T1..T10). */
+    owasp_agentic_top_10_2025: z.array(z.string()).optional(),
+    /** MITRE ATLAS technique IDs (e.g. AML.T0051, AML.T0075). */
+    mitre_atlas: z.array(z.string()).optional(),
+    /**
+     * Cross-framework controls. String format: `<FRAMEWORK>-<VERSION>:<ID>`.
+     * Custom prefixes are first-class (e.g. `INTERNAL-AI-POLICY-3.2:CTRL-7`).
+     */
+    controls: z.array(z.string()).optional(),
+    /**
+     * Risk vocabulary anchored to EU AI Act terminology by default.
+     * Allowed values: `prohibited | high | limited | minimal`.
+     * Other strings (e.g. NIST 800-30 `low | moderate | high`) are accepted with a soft warning.
+     */
+    risk_tier: z.string().optional(),
+    /** Human-readable owner (team name, group). */
+    owner: z.string().optional(),
+  })
+  .passthrough();
+
+export type GovernanceMetadata = z.infer<typeof GovernanceMetadataSchema>;
+
 const MetadataSchema = z.object({
   name: z
     .string()
     .min(1)
     .max(64)
-    .regex(/^[a-z0-9-]+$/),
+    .regex(/^[a-z0-9-]+$/)
+    .optional(),
   description: z.string().min(1).max(1024).optional(),
   version: z.string().optional(),
   author: z.string().optional(),
@@ -17,17 +61,35 @@ const MetadataSchema = z.object({
       agentv: z.string().optional(),
     })
     .optional(),
+  governance: GovernanceMetadataSchema.optional(),
 });
 
 export type EvalMetadata = z.infer<typeof MetadataSchema>;
 
+/**
+ * Extract the governance block from a suite-level YAML. Accepts either:
+ *   - top-level `governance:` (consistent with `description`, `tags`, etc.)
+ *   - nested `metadata.governance:` (matches the case-level shape)
+ * Top-level wins if both are present.
+ */
+function extractGovernance(suite: JsonObject): unknown {
+  if (suite.governance !== undefined) {
+    return suite.governance;
+  }
+  const wrapper = suite.metadata;
+  if (wrapper && typeof wrapper === 'object' && !Array.isArray(wrapper)) {
+    return (wrapper as Record<string, unknown>).governance;
+  }
+  return undefined;
+}
+
 export function parseMetadata(suite: JsonObject): EvalMetadata | undefined {
   const hasName = typeof suite.name === 'string';
-  const hasDescription = typeof suite.description === 'string';
+  const governanceRaw = extractGovernance(suite);
 
-  // Only trigger metadata parsing when `name` is present.
-  // `description` alone doesn't trigger it since it's also used as a regular suite field.
-  if (!hasName) {
+  // Trigger metadata parsing when `name` is present, OR when a governance block exists
+  // (so authors can attach governance to suites that don't have a name).
+  if (!hasName && governanceRaw === undefined) {
     return undefined;
   }
 
@@ -39,5 +101,6 @@ export function parseMetadata(suite: JsonObject): EvalMetadata | undefined {
     tags: suite.tags,
     license: suite.license,
     requires: suite.requires,
+    governance: governanceRaw,
   });
 }

packages/core/src/evaluation/orchestrator.ts

@@ -1369,6 +1369,13 @@ export async function runEvaluation(
           beforeAllOutputAttached = true;
         }
 
+        // Surface case-level metadata (e.g. governance taxonomies) on the result so
+        // it round-trips into the JSONL artifact and downstream consumers (reports,
+        // jq pipelines, attestation exports). Already-set metadata wins.
+        if (evalCase.metadata && !result.metadata) {
+          result = { ...result, metadata: evalCase.metadata };
+        }
+
         if (onProgress) {
           await onProgress({
             workerId,

packages/core/src/evaluation/types.ts

@@ -1160,6 +1160,12 @@ export interface EvaluationResult {
   readonly failureReasonCode?: string;
   /** Structured error detail (only when executionStatus === 'execution_error') */
   readonly executionError?: ExecutionError;
+  /**
+   * Pass-through of `EvalTest.metadata` so case-level information (e.g. governance taxonomies,
+   * skill-name tags) flows into the JSONL artifact and downstream consumers without each
+   * surface having to thread the EvalTest separately.
+   */
+  readonly metadata?: Record<string, unknown>;
 }
 
 export type EvaluationVerdict = 'pass' | 'fail' | 'skip';

packages/core/src/evaluation/validation/eval-validator.ts

@@ -51,6 +51,8 @@ const KNOWN_TOP_LEVEL_FIELDS = new Set([
   'evaluators',
   'preprocessors',
   'workspace',
+  'metadata',
+  'governance',
 ]);
 
 /**
@@ -195,6 +197,10 @@ export async function validateEvalFile(filePath: string): Promise<ValidationResu
   // Validate metadata fields
   validateMetadata(parsed, absolutePath, errors);
 
+  // Soft-warning lint for the optional governance block (suite-level).
+  // Accepts both top-level `governance:` and nested `metadata.governance:`.
+  validateGovernance(extractGovernanceBlock(parsed), 'governance', absolutePath, errors);
+
   // Warn on deprecated or unknown top-level fields
   for (const key of Object.keys(parsed)) {
     const deprecationMessage = DEPRECATED_TOP_LEVEL_FIELDS.get(key);
@@ -457,6 +463,16 @@ export async function validateEvalFile(filePath: string): Promise<ValidationResu
     // Cross-field validation for conversation mode
     validateConversationMode(evalCase, location, absolutePath, errors);
 
+    // Soft-warning lint for case-level governance block.
+    if (isObject(evalCase.metadata)) {
+      validateGovernance(
+        (evalCase.metadata as JsonObject).governance,
+        `${location}.metadata.governance`,
+        absolutePath,
+        errors,
+      );
+    }
+
     await validateWorkspaceConfig(
       evalCase.workspace,
       absolutePath,
@@ -1006,3 +1022,125 @@ function validateConversationMode(
     }
   }
 }
+
+/**
+ * Recognized fields inside the optional `governance` block. Any other key produces a soft
+ * warning so that authors notice typos like `owasp_lm_top_10_2025`. Unknown frameworks (e.g.
+ * a future `iso_42001_2027`) require updating this set in the same PR — that is intentional;
+ * the alternative (silent acceptance) lets typos rot in production evals.
+ */
+const KNOWN_GOVERNANCE_FIELDS = new Set([
+  'schema_version',
+  'owasp_llm_top_10_2025',
+  'owasp_agentic_top_10_2025',
+  'mitre_atlas',
+  'controls',
+  'risk_tier',
+  'owner',
+]);
+
+/** EU AI Act risk-tier vocabulary (the default; other strings produce a soft warning). */
+const EU_AI_ACT_RISK_TIERS = new Set(['prohibited', 'high', 'limited', 'minimal']);
+
+/**
+ * Validates a `<FRAMEWORK>-<VERSION>:<ID>` control string. Custom prefixes are first-class
+ * (e.g. `INTERNAL-AI-POLICY-3.2:CTRL-7`) — only the *shape* is checked. Returns true if the
+ * string has the required `:` separator AND the framework segment ends with a version-looking
+ * token (digit-or-dot suffix, e.g. `1.0`, `2024`, `3.2`). Misses on this heuristic produce
+ * a soft warning, never an error.
+ */
+function isWellFormedControlId(value: string): boolean {
+  const colonIdx = value.indexOf(':');
+  if (colonIdx <= 0 || colonIdx === value.length - 1) {
+    return false;
+  }
+  const prefix = value.slice(0, colonIdx);
+  const lastSegment = prefix.split('-').pop() ?? '';
+  // Version-looking: starts with a digit or contains a dot.
+  return /[0-9]/.test(lastSegment.charAt(0)) || lastSegment.includes('.');
+}
+
+/** Top-level `governance:` wins; falls back to nested `metadata.governance:`. */
+function extractGovernanceBlock(parsed: JsonObject): JsonValue | undefined {
+  if (parsed.governance !== undefined) {
+    return parsed.governance;
+  }
+  if (isObject(parsed.metadata)) {
+    return (parsed.metadata as JsonObject).governance;
+  }
+  return undefined;
+}
+
+function validateGovernance(
+  block: JsonValue | undefined,
+  location: string,
+  filePath: string,
+  errors: ValidationError[],
+): void {
+  if (block === undefined) return;
+  if (!isObject(block)) {
+    errors.push({
+      severity: 'warning',
+      filePath,
+      location,
+      message: `'${location}' must be an object; got ${Array.isArray(block) ? 'array' : typeof block}.`,
+    });
+    return;
+  }
+
+  for (const key of Object.keys(block)) {
+    if (!KNOWN_GOVERNANCE_FIELDS.has(key)) {
+      errors.push({
+        severity: 'warning',
+        filePath,
+        location: `${location}.${key}`,
+        message: `Unknown governance field '${key}'. Known fields: ${[...KNOWN_GOVERNANCE_FIELDS].join(', ')}.`,
+      });
+    }
+  }
+
+  const controls = block.controls;
+  if (controls !== undefined) {
+    if (!Array.isArray(controls)) {
+      errors.push({
+        severity: 'warning',
+        filePath,
+        location: `${location}.controls`,
+        message: "'controls' should be an array of '<FRAMEWORK>-<VERSION>:<ID>' strings.",
+      });
+    } else {
+      for (let i = 0; i < controls.length; i++) {
+        const entry = controls[i];
+        if (typeof entry !== 'string') {
+          errors.push({
+            severity: 'warning',
+            filePath,
+            location: `${location}.controls[${i}]`,
+            message: 'Control entries must be strings.',
+          });
+        } else if (!isWellFormedControlId(entry)) {
+          errors.push({
+            severity: 'warning',
+            filePath,
+            location: `${location}.controls[${i}]`,
+            message: `Malformed control '${entry}'. Expected '<FRAMEWORK>-<VERSION>:<ID>' (e.g. NIST-AI-RMF-1.0:MEASURE-2.7). Custom prefixes are allowed.`,
+          });
+        }
+      }
+    }
+  }
+
+  const riskTier = block.risk_tier;
+  if (
+    riskTier !== undefined &&
+    typeof riskTier === 'string' &&
+    !EU_AI_ACT_RISK_TIERS.has(riskTier)
+  ) {
+    errors.push({
+      severity: 'warning',
+      filePath,
+      location: `${location}.risk_tier`,
+      message: `'risk_tier: ${riskTier}' is outside EU AI Act vocabulary (prohibited | high | limited | minimal). Other vocabularies (e.g. NIST 800-30) are accepted but flagged.`,
+    });
+  }
+}