ADR-0029: Customer AI Governance Outputs

Accepted

Date: 2026-06-25

Context

Every enterprise team that uses Almathal to generate an application inherits an AI governance obligation of their own. The generated app is a software artifact that will run in a regulated environment, potentially handling sensitive data, and produced with the assistance of AI. Under the EU AI Act, NIST AI RMF, and ISO/IEC 42001 — the three governance frameworks most prevalent in enterprise procurement as of 2026 — the team deploying the app must be able to demonstrate:

Where the code came from (provenance)
What licenses it carries
What the security posture of its dependencies is
How the AI was involved in producing it
What decisions the AI made and why

For archetypes that generate AI-using applications (such as the RAG chatbot, MVP Archetype #1), the obligations are deeper: the generated app itself uses an LLM at runtime. That LLM is an AI system with its own governance requirements — risk classification, data flow documentation, model version recording, human-in-the-loop checkpoint documentation.

No other application generation platform currently produces these governance artifacts as standard deliverables. This is a stated competitive differentiator: Almathal’s architecture produces provenance as a byproduct of retrieval-first composition, and that provenance can be packaged as governance documentation without additional platform effort.

Almathal-generated apps must help their deploying teams answer the governance questions their procurement and compliance teams will ask.

Decision

Standard Deliverables (All Archetypes)

Every Almathal-generated application ships with the following as standard, non-optional deliverables:

1. Software Bill of Materials (SBOM) in CycloneDX 1.5 format

Includes all direct and transitive dependencies, their declared licenses, their versions, their checksums, and the Component Library admission status (active, experimental, deprecated) of any curated Adapters in the bill. The SBOM is generated automatically from the resolved Spec and the constituent Adapter Manifests.

The SBOM answers the procurement question: “What is in this software and where did it come from?”

2. License report

A human-readable summary derived from the SBOM:

All licenses present in the generated app, grouped by SPDX identifier
Count of components per license
Flag for any licenses requiring attribution or carrying distribution restrictions
Confirmation that no GPL/AGPL/SSPL components are present (or explicit disclosure if they are, with rationale)

3. Provenance record

For each file in the generated application:

Which Adapter or Seam produced it
The Adapter version and Manifest UUID
Whether it was scaffolded (deterministic) or stitched (LLM-produced)
For stitched files: the Seam ID, the model used, the model version, and the generation timestamp

The provenance record answers the procurement question: “For any file in this codebase, where exactly did it come from?”

4. Generation audit trail

The full pipeline audit trail per ADR-0028:

Every pipeline stage that ran, with timestamps and results
The Spec as approved by the user (including user ID, approval timestamp)
All agent invocations with decision rationale, model version, and session context
Build Verification results (compile, lint, test pass/fail)
AI Reviewer output review warnings

5. Dependency vulnerability snapshot

A CVE snapshot taken at generation time against the resolved dependency versions, using the same scanner (Trivy/Grype) applied during Curation Pipeline admission. Includes:

Scan timestamp
Scanner version and database version
List of any open CVEs found (none expected for curated Adapters, but disclosed if present)
Confirmation of clean bill for all curated components

6. Reproducibility record

The locked Spec in full, recording:

Platform version
Archetype version
All Adapter and Module versions (with UUIDs)
Scaffolder versions
Model ID and model version used by the Stitcher

This record allows the same app to be regenerated identically (subject to model version availability) by any authorized team member.

NIST AI RMF Alignment Mapping

The generation audit trail includes an explicit mapping to NIST AI RMF’s four functions. This is a governance team deliverable — it makes the audit trail readable by compliance and procurement teams who evaluate against NIST, not just by engineers.

NIST AI RMF Function	Almathal Evidence
Govern — accountability structures and culture	User approval recorded at Build Approval; AI autonomy levels declared per ADR-0028; certification roadmap per ADR-0028
Map — risk context and impact	Component Library admission records (license, CVE, security posture); Archetype classification; Stitcher autonomy level for this generation
Measure — risk analysis and testing	Build Verification results (compile, lint, tests); AI Reviewer output review findings; CVE snapshot
Manage — risk response	Curated library as risk-management mechanism; human approval gate; reproducibility record enabling rollback

The mapping is included as a structured JSON block in the audit trail and as a human-readable table in the governance package PDF (see Packaging below).

MVP vs v1 delivery:

MVP: NIST mapping present as structured JSON in the audit trail. Queryable via the audit trail API.
V1: NIST mapping visible in the observability UI; exportable as part of the governance package PDF.

AI Governance Package (AI-Using Archetypes)

For archetypes that generate applications which use AI at runtime — currently the RAG chatbot (Archetype #1) and any future AI-augmented archetypes — an additional AI Governance Package is included as a standard deliverable.

The AI Governance Package addresses the generated application’s own AI governance obligations. The deploying team must be able to demonstrate these obligations to their own regulators and procurement teams.

Package contents:

a) AI System Card

A structured document (machine-readable JSON + human-readable Markdown) describing the AI system embedded in the generated application:

LLM provider and model used at runtime (from the resolved LLM Provider Slot in the Archetype Spec)
Model version as of generation time
Declared capabilities and limitations of the model (sourced from the LLM provider SDK Adapter’s Manifest)
Intended use case (from the Archetype description)
Data flow description: what data enters the LLM (user prompts, retrieved context), what data is returned, whether prompts are logged
Human-in-the-loop checkpoints declared by the Archetype (e.g., citation review, confidence threshold review)

b) Risk classification

Under the EU AI Act’s risk taxonomy, the generated AI-using application is classified. Classification is based on the Archetype’s declared use case:

The RAG chatbot Archetype is classified as Limited Risk (transparency obligations apply: users must be informed they are interacting with AI)
Future Archetypes with higher-risk use cases (HR decision support, credit scoring, medical triage) are classified as High Risk (full conformity assessment required)

The classification is declared in the Archetype definition and recorded in the AI System Card. The deploying team can override the classification with documented rationale if their specific deployment context changes the risk profile.

c) Data flow diagram

An auto-generated diagram showing:

User input path into the LLM (prompt construction, any PII handling notes)
Retrieval path (what corpus is queried, how documents are chunked and embedded)
LLM response path (streaming or batch, any output filtering)
Data retention policy declared by the LLM provider Adapter’s Manifest

d) Human-in-the-loop checkpoint record

Lists every point in the generated application’s runtime flow where a human must review, approve, or override an AI output. These checkpoints are declared in the Archetype definition. The deploying team can use this record to demonstrate to auditors that their AI system has appropriate human oversight.

e) Recommended monitoring checklist

A checklist of ongoing monitoring activities the deploying team should implement:

Response quality monitoring (sample-and-review of LLM outputs)
Retrieval relevance monitoring (are retrieved documents actually relevant to queries?)
Hallucination detection (for factual claims in LLM output)
Model drift monitoring (outputs changing as the model is updated by the provider)
Prompt injection detection (adversarial inputs attempting to override the system prompt)

The checklist is sourced from the LLM provider Adapter’s Manifest and expanded by the Archetype’s declared use case. It is advisory — the deploying team decides which items to implement.

Packaging and Delivery

The governance artifacts are delivered as part of the generated app’s output directory:

generated-app/
├── src/                    ← application source code
├── deploy/                 ← container manifests, helm charts, docker-compose
├── tests/                  ← generated test suites
└── governance/
    ├── sbom.cdx.json                    ← SBOM in CycloneDX 1.5
    ├── license-report.md                ← human-readable license summary
    ├── provenance.json                  ← per-file provenance record
    ├── audit-trail.json                 ← full generation audit trail
    ├── vulnerability-snapshot.json      ← CVE snapshot at generation time
    ├── reproducibility-record.json      ← locked Spec for regeneration
    ├── nist-ai-rmf-mapping.json         ← NIST AI RMF function mapping
    └── ai-governance-package/           ← only present for AI-using archetypes
        ├── ai-system-card.json
        ├── ai-system-card.md
        ├── risk-classification.json
        ├── data-flow-diagram.svg
        ├── human-in-the-loop-checkpoints.md
        └── monitoring-checklist.md

Governance package PDF (v1 feature): A single, formatted PDF combining the human-readable elements of the above, suitable for submission to a procurement team or auditor. Generated on demand via the platform UI or API. Not in MVP scope.

Governance API

An API endpoint for accessing the governance artifacts of any generated app by build ID. Required for enterprise integrations:

Procurement platforms that ingest SBOMs automatically
GRC (Governance, Risk, Compliance) tools that consume structured audit trails
SBOM analysis tools (e.g., FOSSA, Snyk) that accept CycloneDX

The API is authenticated and access-controlled. Only principals with governance role can access the full audit trail. Engineers have access to their own builds.

Rationale

Provenance as a byproduct, not a product feature. The retrieval-first architecture produces provenance naturally — every component has a Manifest, every Manifest has a recorded admission, every generation records which Manifests it used. Packaging this as governance artifacts is primarily a presentation decision, not an engineering one. This is why no other platform does it: you can’t retrofit provenance onto LLM-generated code, but you get it for free from curated composition.

NIST AI RMF mapping in the deliverable makes the audit trail readable to the people who need it. Engineers know what compile and lint mean. Governance teams know what Govern/Map/Measure/Manage mean. The mapping is the bridge.

AI System Card for AI-using archetypes is a competitive differentiator today and a regulatory requirement soon. The EU AI Act’s transparency obligations already apply to limited-risk AI systems. High-risk AI systems face full conformity assessment requirements. An enterprise team deploying a RAG chatbot generated by Almathal should receive documentation that helps them satisfy those obligations, not documentation that stops at “here is the code.”

MVP foundation, v1 completeness. The governance file structure, SBOM, and audit trail are MVP requirements — they are what makes the platform trustworthy from day one. The governance PDF, observability UI, and governance API are v1 completions. The MVP is not a throwaway prototype; it is the foundation on which v1 governance features are built.

Future Considerations

Governance package versioning. As frameworks evolve (NIST publishes autonomous agent standards, EU AI Act enforcement expands), the governance package format will need to evolve. The governance artifacts should be schema-versioned similarly to Manifests and Archetype Specs.

Third-party attestation. A future capability where Almathal issues a signed attestation alongside the governance package, certifying that the artifacts are accurate as of generation time. This would require platform-level signing infrastructure (HSM or similar) and would strengthen the artifacts’ value in formal procurement.

Customer-configurable governance profiles. Different enterprise customers have different governance requirements (US federal vs EU enterprise vs healthcare vs defense). A governance profile system would allow customers to declare their applicable frameworks and have the governance package emphasize the relevant artifacts and mappings. Deferred until the platform has enough enterprise customers to identify the common profiles.

Continuous governance monitoring integration. The governance package is a point-in-time artifact. A future integration with GRC platforms would enable continuous monitoring: the platform pushes updated CVE snapshots and model version change notices as they occur, keeping the customer’s governance record current between generations.

References

ADR-0001: Retrieval-First Architecture — provenance as a structural property of the platform.
ADR-0010: Semver and Compatibility Matrix Versioning — component version locking enables the reproducibility record.
ADR-0012: Sanity Checks at Five Pipeline Stages — Build Verification results are part of the governance package.
ADR-0028: Almathal AI Governance Posture — the platform’s own governance posture; the customer governance outputs defined here are enabled by and extend the internal governance established there.
ADR-0022: RAG Chatbot as MVP Archetype #1 — the first AI-using Archetype requiring the AI Governance Package.
Concepts → Manifest — Manifests carry the provenance data that populates the SBOM and provenance record.
Architecture Overview — Component Library, Module Library, and curation pipeline context.