# Concordia Compliance Templates

Created: **2026-04-23**

Scope: Phase 179 Concordia task `179.1.3.4`.

This directory holds the reference templates Concordia uses for compliance-grade
documentation across four artifact families:

| Template                                                             | Scope                                                                                                                   | Produced for                                             |
| -------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- |
| [`model-card.template.md`](./model-card.template.md)                 | One ML / LLM model used by Concordia (preference ranker, utility model, mediator-assist model, explanation model, etc.) | Every model referenced by a §179.3 or §179.4 deliverable |
| [`system-card.template.md`](./system-card.template.md)               | One deployed Concordia system (the Oshun workbench, an orchestrator, a pilot tenant configuration)                      | Every named Concordia deployment                         |
| [`evaluator-card.template.md`](./evaluator-card.template.md)         | One evaluator used to score runs (fairness instrument, subjective-value instrument, clause-exploit suite, benchmark)    | Every named §179.8 evaluator                             |
| [`policy-bundle-card.template.md`](./policy-bundle-card.template.md) | One domain policy bundle (procurement playbook, restorative template, DAO amendment template, etc.)                     | Every named §179.4.1 / §179.7.\* domain bundle           |
| [`optimizer-card.template.md`](./optimizer-card.template.md)         | One optimization strategy (Nash-GA, NSGA-II, MCTS, CP-SAT, Bayesian, PSRO, coalition search)                            | Every named §179.4.2 optimizer                           |

Each template is a filled-in markdown document at authoring time. The template
fields map to:

- **EU AI Act Article 11 / Annex IV** technical documentation expectations (per
  [`../eu-ai-act-mapping.md`](../eu-ai-act-mapping.md) §Art. 11).
- **NIST AI RMF Govern / Map** function artifacts (per
  [`../nist-ai-rmf-mapping.md`](../nist-ai-rmf-mapping.md) §1–§2).
- **JAMS AI Rules** trade-secret-aware inspection protocol (for cases where the
  card is produced for an arbitration).
- **Mediator.ai's own self-disclosed architecture posture** as a baseline —
  Concordia produces cards that go beyond Mediator.ai's blog post (see
  [`../../research/gap-analysis-mediator-ai.md`](../../research/gap-analysis-mediator-ai.md)).

## Usage

1. Copy a template from this directory into
   `docs/compliance/cards/<domain>/<artifact-slug>.md`.
2. Fill in every field. Do not leave placeholder `TBD` values in a card that
   ships to production; the release gate at §179.10.7 rejects placeholder cards.
3. Link the filled card from the referencing library's README or from
   `libs/openapi/docs/concordia/<artifact>/` so it can be discovered by
   deployers.
4. Reference the card in model or optimizer version metadata per §179.5.3.3 so
   every accepted agreement points back to the specific card version that
   described the model / system / evaluator in play.

## Versioning

Each card has its own `version:` field in the front matter. Bump the version
when:

- The underlying model / system / evaluator / policy changes meaningfully (new
  weights, new prompt, new scoring rule).
- A fairness, accuracy, or robustness metric in the card materially shifts.
- An incident report (§179.5.3.4) implicates this artifact and triggers a
  documentation update.

Old versions are preserved in git history; the current version is the
head-of-main copy of the file. A card version is the attestation deployers and
reviewers rely on at the time of an accepted agreement, so it must be pinned —
`optimizerCardVersion`, `modelCardVersion`, etc. — alongside the usual
model-version pinning at §179.5.3.3.

## Refresh

Cards are re-reviewed at every refresh-gate firing per
[`../../research/refresh-gate.md`](../../research/refresh-gate.md) §R5. A
failing refresh on the card set (missing required fields, stale evaluation
numbers, unlinked from the referencing code) blocks the phase transition or
pilot launch.

## Populated cards (Concordia v1.0.0)

The §179.10.7 governance review approves the v1.0.0 release on the cards
populated under [`../cards/concordia/`](../cards/concordia/):

- Models:
  [pairwise-preference-ranker](../cards/concordia/models/pairwise-preference-ranker.md),
  [utility-fitters](../cards/concordia/models/utility-fitters.md).
- Optimizers: [nash-genetic](../cards/concordia/optimizers/nash-genetic.md),
  [nsga-ii](../cards/concordia/optimizers/nsga-ii.md),
  [map-elites](../cards/concordia/optimizers/map-elites.md),
  [mcts-lats](../cards/concordia/optimizers/mcts-lats.md),
  [cp-sat](../cards/concordia/optimizers/cp-sat.md),
  [bayesian-optimization](../cards/concordia/optimizers/bayesian-optimization.md),
  [psro-opponent-model](../cards/concordia/optimizers/psro-opponent-model.md),
  [coalition-stability](../cards/concordia/optimizers/coalition-stability.md).
- Evaluators:
  [preference-stability](../cards/concordia/evaluators/preference-stability.md),
  [baseline-benchmark-gate](../cards/concordia/evaluators/baseline-benchmark-gate.md),
  [fairness-suite](../cards/concordia/evaluators/fairness-suite.md).
- Policy bundles:
  [maat-procurement-standard](../cards/concordia/policy-bundles/maat-procurement-standard.md),
  [themis-dao-governance-standard](../cards/concordia/policy-bundles/themis-dao-governance-standard.md),
  [kuanyin-restorative-standard](../cards/concordia/policy-bundles/kuanyin-restorative-standard.md).
- System:
  [concordia-workbench](../cards/concordia/systems/concordia-workbench.md).

The governance review record is at
[`../governance-reviews/179.10.7-concordia-governance-review.md`](../governance-reviews/179.10.7-concordia-governance-review.md).
Domain pilots beyond the three first-pilot domains require their own populated
policy-bundle card before launch (carried as a condition by the governance
review).