The .swt3-gate.yml Configuration Guide: Policy as Code for AI Compliance

0. Prerequisites

# Python
pip install swt3-ai

# TypeScript / Node.js
npm install @tenova/swt3-ai

The gate parser requires PyYAML (Python) or the yaml npm package (TypeScript). Both are installed automatically with the SDK.

1. What is a Gate Config?

A .swt3-gate.yml file defines which SWT3 procedures must have recent, passing verdicts before your system is considered compliant. It answers three questions:

• Which procedures are required? (e.g., AI-INF.1, AI-FAIR.1, AI-SEC.1)
• How fresh must the evidence be? (e.g., "witnessed within the last 7 days")
• Which failures are critical? (e.g., stale safety procedures fail the gate immediately)

Place the file at the root of your repository. The CLI auto-discovers it by searching up to 10 parent directories. Accepted filenames: .swt3-gate.yml, swt3-gate.yml, .swt3-gate.yaml, swt3-gate.yaml.

2. Quick Start

Create a file named .swt3-gate.yml in your project root:

version: "1.0"
name: "My AI Service Policy"
strict: false

models:
  chatbot-v2:
    risk: "high"

defaults:
  gates:
    - procedure: AI-INF.1
      required: true
      max_age: 7d
    - procedure: AI-LOG.1
      required: true
      max_age: 7d

Validate it:

swt3 gate --validate

Set your API key and evaluate against your live ledger:

# Set your API key (get one from your dashboard Settings page)
export SWT3_API_KEY=axm_live_your_key_here

# Evaluate (uses "defaults" section when no framework is specified)
swt3 gate

Sample output:

PASS  AI-INF.1   Inference Provenance        witnessed 2h ago (max: 7d)
PASS  AI-LOG.1   Audit Logging               witnessed 2h ago (max: 7d)

Gate: PASS  (2 passed, 0 warned, 0 failed)
# Exit code: 0

3. Full Spec Reference

Framework Structure

Gate Group Structure

Procedure Gate Entry

4. Framework-Specific Gates

Gates are organized by regulatory article within each framework. This structure maps directly to the assessor's evaluation criteria:

frameworks:
  eu-ai-act:
    risk_class: "high-risk"
    gates:
      - group: "Article 9: Risk Management"
        procedures:
          - procedure: AI-SAFE.1
            required: true
            max_age: 7d
            critical: true
            ref: "Art. 9(2)"
            description: "Safety boundary verification"
            hint: "witness.witnessSafety()"

      - group: "Article 10: Data Governance"
        procedures:
          - procedure: AI-FAIR.1
            required: true
            max_age: 7d
            critical: true
            ref: "Art. 10(2)(f)"
            description: "Bias and fairness attestation"
            hint: "witness.witnessFairness()"

The group field is for human readability and assessor presentation. It does not affect evaluation logic. Procedures within a group are evaluated independently.

Defaults vs. Frameworks

Defaults are additive. Procedures listed in the defaults section apply to every evaluation regardless of which framework you select. If a procedure appears in both defaults and a framework section, the framework-level entry takes precedence for that framework. Use defaults for baseline procedures that apply everywhere (e.g., AI-LOG.1, AI-AUDIT.1), and frameworks for regulation-specific requirements.

If your config only has a defaults section and no frameworks, run evaluation without the --framework flag: swt3 gate. The CLI evaluates defaults automatically.

5. Generating a Config

Instead of writing YAML by hand, generate a config from any of 18 supported frameworks:

# Generate an EU AI Act gate config
swt3 gate --init --framework EU-AI-ACT

# Generate for SR 11-7 (financial model risk)
swt3 gate --init --framework SR-11-7 --output .swt3-gate.yml

# Generate with strict mode and a custom name
swt3 gate --init --framework NIST-AI-RMF --strict --name "ACME AI Policy"

# List all available frameworks
swt3 gate --init --json

The generator uses the framework crosswalk database to produce a config with procedures grouped by regulatory article, descriptions, SDK hints, references, and recommended max_age and critical settings. The generated config includes a crosswalk_hash for integrity tracking.

Generated configs are starting points. Edit them to match your organization's risk appetite: adjust max_age thresholds, mark additional procedures as critical, or remove procedures that are not applicable to your deployment.

6. Validating a Config

Validate your config offline (no API call, no credentials required):

# Validate the auto-discovered config file
swt3 gate --validate

# Validate a specific file
swt3 gate --validate --config /path/to/gate.yml

# JSON output for scripting
swt3 gate --validate --json

Validation checks: version field is present and is "1.0", procedure IDs match the required format (AI-[A-Z]+.\d+), max_age values parse correctly (1-90d, 1-24h, 1-1440m), no unknown top-level keys, and no duplicate procedures within a framework.

7. Evaluating Against Live Data

Evaluate your config against the live compliance ledger:

# Evaluate the EU AI Act framework gates
swt3 gate --framework eu-ai-act

# Evaluate for a specific model
swt3 gate --framework eu-ai-act --model chatbot-v2

# JSON output
swt3 gate --framework eu-ai-act --json

The CLI posts your config to POST /api/v1/gate/evaluate, which checks each procedure against the latest verdict in the ledger. Requires SWT3_API_KEY environment variable.

Decision Logic

Overall gate roll-up: Any FAIL = gate FAIL. No FAIL but any WARN = gate WARN. All PASS = gate PASS.

Sample Output (FAIL)

PASS  AI-INF.1   Inference Provenance        witnessed 2h ago (max: 7d)
FAIL  AI-FAIR.1  Bias and Fairness           no verdict found (required)
WARN  AI-SEC.1   Security Classification      witnessed 9d ago (max: 7d, not critical)
PASS  AI-LOG.1   Audit Logging               witnessed 2h ago (max: 7d)

Gate: FAIL  (2 passed, 1 warned, 1 failed)

8. CI/CD Integration

The swt3 gate command returns exit code 0 for PASS, exit code 1 for FAIL or WARN. In CI/CD, both FAIL and WARN block the pipeline by default. To allow warnings to pass, add --warn-ok which returns exit code 0 for both PASS and WARN.

GitHub Actions

- name: SWT3 Compliance Gate
  env:
    SWT3_API_KEY: ${{ secrets.SWT3_API_KEY }}
  run: swt3 gate --framework eu-ai-act

GitLab CI

compliance_gate:
  script:
    - swt3 gate --framework eu-ai-act
  allow_failure: false

If the gate fails, the pipeline stops. The developer fixes the compliance gap (run the missing witness, update the model, re-attest) and re-runs the pipeline. The assessor sees the same config file in version control and can evaluate it independently.

9. Example Configs

Minimal (defaults only)

version: "1.0"
defaults:
  gates:
    - procedure: AI-INF.1
      required: true
      max_age: 7d

Multi-framework (EU AI Act + SR 11-7)

version: "1.0"
name: "ACME FinTech AI Policy"
strict: true

models:
  fraud-detector-v3: { risk: "high" }
  chatbot-v2: { risk: "medium" }

defaults:
  gates:
    - procedure: AI-LOG.1
      required: true
      max_age: 7d
    - procedure: AI-AUDIT.1
      required: true
      max_age: 7d

frameworks:
  eu-ai-act:
    risk_class: "high-risk"
    gates:
      - group: "Article 9: Risk Management"
        procedures:
          - { procedure: AI-SAFE.1, required: true, max_age: 24h, critical: true }
      - group: "Article 10: Data Governance"
        procedures:
          - { procedure: AI-FAIR.1, required: true, max_age: 7d, critical: true }

  sr-11-7:
    risk_class: "model-risk"
    gates:
      - group: "Model Development"
        procedures:
          - { procedure: AI-MDL.1, required: true, max_age: 7d }
          - { procedure: AI-MDL.5, required: true, max_age: 7d }

10. References

• Assessor Gate Evaluation Guide - How assessors review gate configs in the audit portal
• Assessor Hot Sheet - Two-page printable for assessment meetings
• Developer CI/CD Guide - Full CI/CD integration patterns
• SDK Documentation - Python, TypeScript, and all SDK reference
• UCT Registry - Complete procedure catalog (113 procedures, 61 Namespaces)
• Anchor Verifier - Verify any SWT3 Witness Anchor fingerprint