engmodel

engineering-model-go

engineering-model-go is a Go library and CLI for generating architecture views and AsciiDoc documentation from a typed engineering model.

It combines:

• architecture model loading and validation
• viewpoint projection (architecture-intent/communication/deployment/security/traceability)
• Mermaid rendering
• Structurizr DSL export
• Threat Dragon/Open Threat Model JSON export
• TRLC requirements export
• LOBSTER activity trace export
• design + requirement narrative generation to AsciiDoc
• EARS requirement preflight linting
• code trace mapping (Go, Python, JavaScript, TypeScript, Rust, Verilog modules)

YAML remains the canonical authored and persistence format, with CUE as the authoritative schema and cross-field constraint layer. The canonical YAML/CUE model is a semantic superset of the pinned formal SysML 2.0/KerML 1.0 abstract syntax, with typed Engineering:: extensions. This is evidenced by exhaustive inventory coverage, official-parser validation, and semantic project-interchange round trip. It does not claim execution/simulation semantics or graphical concrete syntax. SysML textual DSL is generated output, not another source model. See docs/sysml-v2-superset-plan.md.

Each model directory has one schema-v2 manifest entry point and eight required domain documents. An optional ninth documents.aviation document adds an airborne software evidence-readiness profile without changing models that omit it:

schemaVersion: 2
module:
  path: models.example/example-system@v0
  version: v0.1.0
  modelId: example-system
  title: Example System
  introduction: Example schema-v2 model.
  kind: system
documents:
  catalog: model/catalog.yml
  requirements: model/requirements.yml
  architecture: model/architecture.yml
  behavior: model/behavior.yml
  assurance: model/assurance.yml
  compliance: model/compliance.yml
  views: model/views.yml
  decisions: model/decisions.yml
  # aviation: model/aviation.yml
dependencies: []
publications:
  - id: public
    architecture: [FU-EXAMPLE]
    requirements: [REQ-EXAMPLE-001]
inferenceHints: {}

engmod.yml is the only model entry point. Every manifest and domain document uses schemaVersion: 2; paths are explicit and no companion filename is inferred. AI agents should call the no-argument MCP tool model.authoringContract first; it returns the resolved document set, schema files, top-level YAML fields, stable-ID conventions, dependency/source rules, and recommended editing order without requiring a broad repository scan.

Scope

This project models development-state architecture inputs from YAML and produces deterministic documentation/view artifacts.

It is not a runtime observability or incident/compliance runtime system.

Features

• CUE-backed, closed-schema YAML loading for architecture, catalog, requirements, decisions, and design documents, followed by strict Go decoding
• format-neutral document definitions and document-control metadata for downstream formal-document generators
• model validation for IDs, references, relations, and viewpoint configuration
• expanded mapping relation taxonomy for communication/deployment/security/traceability/lifecycle semantics
• catalog-linked architecture relation labeling
• deployment view extraction from:
  • Terraform (.tf) using HashiCorp HCL parsing
  • Flux resources (GitRepository/Kustomization/HelmRelease)
  • Helm chart metadata via Helm SDK chart loader
• deterministic Mermaid view rendering
• canonical semantic projection with stable IDs, typed relationships, ownership, source metadata, and explicit unsupported/lossy diagnostics
• deterministic SysML v2 textual projection and executable coverage manifest
• optional DO-178C/ED-12C evidence-readiness modeling and deterministic draft package generation; this is not a compliance or certification determination
• AsciiDoc architecture generation with chapter scope diagrams
• view-level filtering controls (includeKinds, excludeKinds, includeMappings, excludeMappings, maxDepth)
• EARS preflight linting via github.com/labeth/ears-lint-go
  • lintRun.mode: strict is the default and recommended project mode
  • guided is optional for drafting workflows and non-blocking author guidance
• Tree-sitter based code symbol extraction and trace mapping for:
  • Go
  • TypeScript/TSX
  • JavaScript (.js, .mjs, .cjs): named functions/generators, methods, classes and directly bound function values. Anonymous callbacks and top-level statements are not independent declarations; this does not infer classic-script load order or runtime behavior. Syntax errors and multiple declarations on one line produce errors rather than ambiguous trace credit.
  • Python (.py): functions (including async and nested definitions), methods and classes. Decorated declarations retain their definition-line coordinates; multiline decorators do not detach preceding trace comments. Strings and docstrings cannot create trace or ownership markers. Syntax errors fail declaration coverage. Lambdas and top-level script effects are outside this declaration scope. test_*.py and *_test.py are verification sources, with not-run status until result evidence is supplied.
  • Rust
• Lexical Verilog (.v) module trace extraction, with one requirement-link block per module. This does not validate HDL syntax, elaborate designs, or expand macros. Unresolved macro invocations that may affect module declarations and malformed module boundaries produce errors. Macros recognized in expression positions inside a module produce warnings requiring independent build evidence; conditional branches are all inspected. The whole module root is scanned; inferenceHints.exclude takes glob patterns (dir/** for subtrees) for paths to leave out. Linked tb_*.v and *_tb.v testbenches produce verification links with not-run status until result evidence is supplied. Test-source links do not count as production implementation in the trace matrix.

Installation

go get github.com/labeth/engineering-model-go

Library API

Primary entry points:

• GenerateFromFile(architecturePath, viewID)
• Generate(bundle, viewID)
• GenerateAsciiDocFromFiles(architecturePath, requirementsPath, designPath, options)
• GenerateStructurizrDSLFromFile(architecturePath)
• model.ProjectSemanticModel(bundle)
• GenerateSysMLV2FromFile(architecturePath)
• GenerateSysMLV2(bundle)
• GenerateAirborneAssuranceFromFile(manifestPath, options)

For a model that declares documents.aviation, generate the readiness package:

go run ./cmd/engair --model engmod.yml --out-dir generated/do178c \
  --date 2026-09-19 --version v0.1.0

The package is visibly marked DRAFT / NOT A COMPLIANCE OR CERTIFICATION DETERMINATION, identifies exact authored baselines and open gaps, and uses only customer-supplied opaque objective references. See examples/dal-c-flight-control-sample/.

• GenerateSysMLV2Projection(semanticModel)
• SysMLV2Coverage()
• GenerateThreatModelExportFromFile(architecturePath, options)
• GenerateTRLCRequirementsFromFile(requirementsPath, options)
• GenerateLobsterActivityTraceFromDir(testsDir, options)
• BuildTraceMatrixFromFiles(architecturePath, requirementsPath, options)

Example:

res, err := engmodel.GenerateFromFile("examples/payments-engineering-sample/engmod.yml", "VIEW-ARCHITECTURE-INTENT")
if err != nil {
    panic(err)
}

fmt.Println(res.Mermaid)
for _, d := range res.Diagnostics {
    fmt.Printf("%s [%s] %s\n", d.Code, d.Severity, d.Message)
}

View IDs are free-form, but view kind must be one of:

• architecture-intent
• communication
• deployment
• security
• traceability
• state-lifecycle (optional)
• interaction-flow (optional)

Optional view projection controls in model/views.yml:

• includeKinds / excludeKinds: node kind filtering
• includeMappings / excludeMappings: relation type filtering
• maxDepth: bounded traversal from roots (0 means unlimited/default behavior)
• audience, abstraction: optional publication metadata

Formal-document consumers can select canonical model content without adding format-specific payloads:

documents:
  - id: DOC-SYSTEM-SPECIFICATION
    title: System Specification
    kind: system-requirements-specification
    purpose: Define the system requirement baseline.
    audience: [systems-engineering, verification]
    stakeholderRefs: [ACT-SYSTEMS-ENGINEER]
    referenceRefs: [REF-SOURCE-SPECIFICATION]
    contentRefs: [REQ-SYSTEM-001, FU-CONTROL, VIEW-LOGICAL]
    sections:
      - id: scope
        title: Scope
        narrative: Defines the system boundary and intended use.
        includeRefs: [FU-CONTROL]
    control:
      identifier: SYS-SPEC-001
      revision: "1.0"
      status: draft
      issuedBy: Example Organization
      issueDate: 2026-09-20
      language: en
      documentType: specification
      confidentiality: internal
      securityClassification: unclassified
      exportControlled: false
      countryOfOrigin: Sweden
      confidentialityStamp: false

Requirements may additionally declare title, category, rationale, sourceRefs, verificationMethods, verificationCriteria, priority, criticality, status, derived, derivedRationale, and tags. These fields remain generic model input; exporters use only fields that have a native representation in their target format.

Authored architecture optionally supports additional first-class entities:

• interfaces
• dataObjects
• deploymentTargets
• controls
• trustBoundaries
• states
• events
• flows (with ordered steps)
• hardwareItems (physical items with DO-254 DAL safety levels, part numbers, suppliers)
• hardwareInterfaces (HW/SW interface contracts: ICD/IRS with buses such as arinc429, can, spi, i2c, ethernet, cellular)

Structural composition entities in model/architecture.yml:

• contract (the system's provides/requires public interface contract)
• composition.subsystems (downward references to child system models)
• composition.allocations (parent-requirement allocation onto a subsystem or hardware item)
• composition.satisfactions (records of how a subsystem's required interface is satisfied by a provider)

engdoc renders HW/SW interface allocation views from hardwareItems, hardwareInterfaces, and composition.allocations. See System-of-Systems Composition for the composition gates.

Flow step fields (model/behavior.yml behavior.flows[].steps[]) support:

• id, ref, kind, action
• dataIn, dataOut
• next, onError
• async, optional

Assurance authoring fields in model/assurance.yml:

• controls
• risks
• poamItems

OSCAL catalog/profile integration is authored in model/compliance.yml:

• compliance.profiles[]: OSCAL profile/catalog sources for the selected baseline
• compliance.mappings[]: maps local CTRL-* implementation controls to selected OSCAL controlIds and architecture appliesTo entities; unmapped controls remain local model controls and are not exported as OSCAL implementations

Expanded mapping relation vocabulary includes:

• Base: contains, depends_on, interacts_with, targets
• Communication/data: calls, publishes, subscribes, reads, writes, streams
• Traceability/deployment: implements, satisfies, allocated_to, verified_by, deployed_to
• Security/lifecycle: mitigated_by, bounded_by, transitions_to, triggered_by, guarded_by
• Flow projection (view-only): flow_next, flow_error, flow_async, flow_ref

bounded_by links a functional unit, deployment target, interface, actor, hardware item or data object to a trust boundary. Default security views retain these member kinds. Membership describes the modeled boundary; it does not establish authentication or enforcement. Author an explicit relationship when it should appear in the projected view.

Optional per-view publication metadata (in model/views.yml):

• authoredStatus (for example draft, in-review, stable)
• authoredStatusExplanation (short rationale shown in Document Health Snapshot)

Verification metadata is inferred from test artifacts:

• test sources under tests/ (for inferred verification checks and test code element links)
• result artifacts under test-results/ (for inferred requirement-level outcomes)
• requirement IDs in test sources are inferred from TRLC-LINKS: REQ-* markers
• requirement IDs in result artifacts are inferred by matching REQ-* tokens in result content
• published verification chain is Verification Check -> Test Code Element -> Requirement
• functional ownership in verification tables is shown as derived context from requirement ownership
• strict EARS lint also warns when catalog terms (systems, actors, events, states, features, modes, conditions, data terms) are referenced nowhere in the model (catalog.term_unreferenced): a term counts as referenced when its id is used by a model document or its name or an alias appears in requirement text, notes, verification criteria or rationale, another catalog entry's name or definition, or any architecture, behavior, assurance, compliance, views or decisions text

Code trace markers

Source files link back to the model with two comment markers, scanned under --code-root:

• TRLC-LINKS: lists requirement IDs (REQ-*) implemented or exercised by the code
• ENGMODEL-LINKS: lists model element IDs (functional units, interfaces, controls, flows, data objects, etc.) realized by the code

Both markers are validated against the loaded model. Unresolved IDs are hard errors (code.dangling_requirement_link for TRLC-LINKS, code.dangling_model_link for ENGMODEL-LINKS), enforced by the engdoc zero-error gate and by engtrace (non-zero exit). Code is scoped to its nearest enclosing model root, so links resolve against the closest model rather than the whole tree. Requirements with no implementing or delegating code surface a requirement.orphan warning, and a requirement linked from code that does not exist raises requirement.internal_link.

CLI Usage

Plan, inspect, and atomically apply a requirements delta:

# requirements-delta.yml
version: 1
requirements:
  add:
    - id: REQ-PAY-011
      text: "When payment authorized event is received, the payments system shall persist authorization record."
      notes: "New audit behavior."
      appliesTo: [FU-PAYMENT-AUTHORIZATION]
  update: []
  remove: []

go run ./cmd/engchange validate --root examples/payments-engineering-sample --delta requirements-delta.yml
go run ./cmd/engchange diff --root examples/payments-engineering-sample --delta requirements-delta.yml
go run ./cmd/engchange apply --root examples/payments-engineering-sample --delta requirements-delta.yml

Delta version 1 supports requirement add, whole-entity update, and remove operations. Planning and diffing never write canonical files. Apply validates the complete candidate model, preserves unchanged YAML nodes and comments, and atomically replaces model/requirements.yml only when no blocking diagnostics are present.

Generate a single Mermaid view:

go run ./cmd/engview \
  --model examples/payments-engineering-sample/engmod.yml \
  --view VIEW-DEPLOYMENT \
  --out out.mmd

Generate every authored view as deterministic Mermaid and native SVG:

go run ./cmd/engview \
  --model examples/coffee-appliance-six-view/engmod.yml \
  --out-dir examples/coffee-appliance-six-view/generated

The coffee appliance fixture demonstrates use-case, logical, process, physical, implementation, and deployment concerns from canonical schema-v2 semantics. Its process output is a Mermaid sequence diagram, and every SVG includes an accessible title plus source and view provenance.

Generate architecture AsciiDoc:

go run ./cmd/engdoc \
  --model examples/payments-engineering-sample/engmod.yml \
  --requirements examples/payments-engineering-sample/model/requirements.yml \
  --design examples/payments-engineering-sample/model/views.yml \
  --code-root ./src \
  --view VIEW-ARCHITECTURE-INTENT \
  --view VIEW-TRACEABILITY \
  --decisions-out examples/payments-engineering-sample/generated/DECISIONS.adoc \
  --out examples/payments-engineering-sample/generated/ARCHITECTURE.adoc

--view is repeatable to scope the document to specific viewpoint IDs (omit to include all configured views). When --decisions-out is set, engdoc emits the architecture decision records (from model/decisions.yml) as a separate DECISIONS.adoc document.

Each authored view and each requirement coverage graph is published as one complete diagram. Large diagrams scale to fit the page instead of being split into repeated panels. Standalone Mermaid and SVG exports preserve the same complete graph and can be viewed at a larger scale. Deployment publications shorten relationship labels longer than 32 characters to numbered arrows and retain their full text in a table directly below the diagram. Extra routing space separates keyed edges; standalone graph exports retain the original labels. Browser and requirement flowcharts use wider spacing to reduce label collisions without removing nodes or relationships.

Generate the machine-readable traceability matrix:

go run ./cmd/engtrace \
  --model examples/payments-engineering-sample/engmod.yml \
  --requirements examples/payments-engineering-sample/model/requirements.yml \
  --code-root examples/payments-engineering-sample/src \
  --format json \
  --out examples/payments-engineering-sample/generated/TRACE-MATRIX.json

Use --format csv for a spreadsheet-friendly matrix instead. The emitted matrix rolls up per-requirement status (implemented/verified/delegated/orphan) together with code references and delegations. engtrace exits non-zero when it finds dangling code trace links (code.dangling_requirement_link / code.dangling_model_link), so it doubles as a CI gate.

Generate Threat Dragon/Open Threat Model exports:

go run ./cmd/engdragon --model examples/payments-engineering-sample/engmod.yml --format threat-dragon-v2 --out examples/payments-engineering-sample/generated/threat-dragon-v2.json
go run ./cmd/engdragon --model examples/payments-engineering-sample/engmod.yml --format open-otm --out examples/payments-engineering-sample/generated/open-threat-model.json

Generate Structurizr DSL:

go run ./cmd/engstruct --model examples/payments-engineering-sample/engmod.yml --out examples/payments-engineering-sample/generated/STRUCTURIZR.dsl

Generate the deterministic SysML v2 textual projection:

go run ./cmd/engsysml \
  --model examples/payments-engineering-sample/engmod.yml \
  --out examples/payments-engineering-sample/generated/architecture.sysml

Author NATO Architecture Framework 4.1 metadata in model/views.yml without duplicating the canonical architecture graph:

naf:
  framework: NAF
  version: "4.1"
  architectureDescription: Example NAF Architecture Description
  stakeholders:
    - actorRef: ACT-ARCHITECT
      role: Owns architecture decisions.
  concerns:
    - id: NAF-CONCERN-STRUCTURE
      name: System structure
      stakeholderRefs: [ACT-ARCHITECT]
  products:
    - id: NAF-P2-RESOURCE-STRUCTURE
      viewpoint: P2
      title: Physical resource structure
      viewRef: VIEW-DEPLOYMENT
      concernRefs: [NAF-CONCERN-STRUCTURE]

Each NAF product references an existing Engmod view. Capability, service, logical, resource, interface, behavior, and requirement concepts therefore remain represented once in the canonical SysML/KerML-aligned model. Generate the deterministic NAF architecture document with:

go run ./cmd/engnaf \
  --model engmod.yml \
  --out generated/ARCHITECTURE.naf.adoc

The profile accepts the official NAF 4.1 viewpoint codes (C*, S*, L*, P*, and A*, including roadmap and cross-domain viewpoints). CUE rejects unsupported framework versions and viewpoint codes; model validation also checks actor, stakeholder, concern, and Engmod view references. This output is a framework-aligned architecture description and is not a claim of NATO certification.

Emit the executable metaclass/property-level coverage manifest:

go run ./cmd/engsysml --coverage

The formal metamodel inventory is separate from that projection report. The formal Systems-Modeling/SysML-v2-Release tag 2026-04 is pinned at commit 9baca5908ca28b53da085de69336fde48420ea8f. That release does not contain a normative metamodel XMI/Ecore: its XMI directories are standard-library model instances, and the release notes explicitly state that their Eclipse XMI is not fully normative OMG XMI.

The closest official machine-readable metamodel artifact is therefore the Ecore published by the aligned official Pilot Implementation tag 2026-04, commit 20897e3122f2c2f8b29389745f0caaaeb7c6e21a:

Exact immutable URLs and authority notes are tracked in tools/sysml/metamodel-sources.json. Refresh downloads into the ignored .engmod/cache tree, verifies both hashes, and regenerates the compact inventory and semantic coverage binding:

scripts/refresh-sysml-metamodel.sh
scripts/check-sysml-metamodel.sh

The offline check uses only tracked artifacts. It inventories exactly 175 metaclasses, 415 owned properties, 13,318 effective properties, 209 inheritance edges, 328 derived properties, and 66 relationships. The strict binding records 262 mapped entries, 328 derived/implied entries, and zero unimplemented entries. Textual rendering classifies 54 metaclasses as native-rendered and 121 as abstract/implicit, with zero missing rules; all 66 relationships are classified. CI rejects stale inventory hashes, omitted properties or renderer classifications, partial/unsupported normative statuses, stale coverage JSON, official-parser failures, and semantic round-trip differences.

Install the pinned official parser wrapper and Sysand KPAR packager into the ignored .engmod tool/cache tree:

scripts/install-sysml-toolchain.sh

The installer verifies the official 2026-04 Pilot Implementation jupyter-sysml-kernel-0.59.0.zip checksum and the platform-specific Sysand 0.2.1 release checksum. The validator wrapper is checked out at commit 63abbd9fbc7851dc437d01b2dc07836b919770b8; GitHub does not publish a separate source-archive checksum for that commit, so the immutable Git object ID is the documented verification boundary.

Build and reopen a normative KPAR through Sysand:

go run ./cmd/engsysml \
  --model engmod.yml \
  --project-out .engmod/validation/sysml/project \
  --kpar-out .engmod/validation/sysml/engineering-model.kpar \
  --sysand .engmod/tooling/bin/sysand

go run ./cmd/engsysml \
  --model engmod.yml \
  --verify-kpar .engmod/validation/sysml/engineering-model.kpar \
  --reopen-out .engmod/validation/sysml/reopened \
  --sysand .engmod/tooling/bin/sysand

engsysml delegates KPAR creation and reopening to Sysand; it does not create or label a custom ZIP as KPAR. The generated project contains only native SysML source; engineering-model data without a native SysML representation is omitted rather than embedded in descriptions, metadata payloads, or extension bags. Verification reopens the KPAR and compares its SysML source byte-for-byte with a fresh deterministic projection. Run the complete blocking gate with scripts/validate-sysml.sh. Local users may explicitly skip unavailable external tools with ENGMOD_SYSML_SKIP_EXTERNAL=1 scripts/validate-all.sh; CI installs the pinned tools and never sets that skip.

The exporter preserves engineering-specific concepts and source properties in a typed metadata payload and reports unsupported, lossy, external-endpoint, and toolchain-conformance limitations as diagnostics. The generated text and KPAR are validated by the official parser baseline, but the coverage manifest still describes a documented subset/projection rather than claiming complete SysML v2 semantic conformance.

Every authored YAML document is validated against the embedded modular schemas in model/schema/ before strict Go decoding. CUE is authoritative for document shape and cross-field constraints, produces path-aware diagnostics, and rejects unknown fields recursively. A reflection-based contract test detects drift between CUE fields and the Go runtime API representations. The loader aggregates the domain documents into one canonical semantic graph for validation and projection.

Generate TRLC requirements package:

go run ./cmd/engtrlc --requirements examples/payments-engineering-sample/model/requirements.yml --out-dir examples/payments-engineering-sample/generated/trlc --package PaymentsRequirements

Generate LOBSTER activity trace from tests:

go run ./cmd/englobster --tests-dir examples/payments-engineering-sample/tests --requirements-package PaymentsRequirements --activity-namespace tests --out examples/payments-engineering-sample/generated/lobster/activities.lobster

Regenerate all maintained examples with scripts/generate-examples.sh. After generation, scripts/render-publication-pdfs.sh renders the self-model and every example architecture publication using the locally installed proven-docs. Review the rendered pages before release; a successful render does not establish visual quality. PDF rendering is separate from deterministic model-export validation.

Render an individual PDF with proven-docs:

proven-docs render \
  examples/payments-engineering-sample/generated/ARCHITECTURE.adoc \
  --output examples/payments-engineering-sample/generated/ARCHITECTURE.proven.pdf

The generated document starts with:

• Introduction (from model.introduction)
• Scope and Assumptions
• How To Read This Document
• Document Health Snapshot (per-view coverage and confidence)
• Terms and Definitions as a compact Term | Definition table
  • terms are sorted A-Z by term text
  • term IDs are shown as Term (ID) in the term column

Each generated view includes:

• What This View Answers
• Coverage Gaps and Recommended Next Evidence Additions
• view-scoped narratives from model/views.yml
  • for security, content is organized as attack-vector chapters with per-attack diagrams and related FU sections

The Traceability View includes:

• Requirement-to-Unit Mapping (Compact)
• Verification Result Mapping (inferred per-requirement outcomes)

The traceability appendix includes:

• Requirement Details
• Verification Inventory (inferred test/check mappings to test code elements and requirements)
• Reference Index with consistent entry layout:
  • chapter per ID
  • short prose description
  • compact key/value table with the most relevant fields
  • Mentioned In backlinks to jump from registry entries to sections where each entry is referenced
  • sections: Authored References, Catalog References, Inferred Runtime References, Inferred Code References, Verification References

Machine-oriented development context is exposed through the MCP server.

Run the MCP server (Model Context Protocol, stdio JSON-RPC over Content-Length-framed messages on stdin/stdout):

go run ./cmd/engmcp

It exposes 50+ tools grouped into families, including:

• requirements.*: requirement details, impact, support paths, and edit-plan suggestions
• files.*: files and ownership for a requirement, control, or threat
• verification.*: inferred verification status, gaps, and recommendations
• threats.*: threat coverage, per-requirement threats, and unmitigated threats
• flows.*: interaction-flow projections and diffs per requirement
• graph.*: model graph search, neighborhood, and edge explanations
• model.*: model entity lookup, listings, implementations, and RSL export
• interfaces.*: software and HW/SW interface resolution and code matching
• composition.resolve: the system-of-systems — subsystems, contracts, requirement allocations with the delegated subsystem requirement, and composition diagnostics
• trace.matrix: summary (requirements, implemented, tested/testLinked, passed, delegated, orphan, dangling; verified is a deprecated alias of testLinked), per-requirement status, code references, and dangling code trace links; summaryOnly: true returns only the summary and diagnostics
• gemara.*: one tool per OpenSSF Gemara artifact type plus gemara.validate

Additional export/validation docs:

• MCP-first agent workflow and tagging contract: docs/skills/architecture-mcp-workflow.md
• OSCAL profile/catalog and compliance mapping workflow: docs/oscal-compliance-mapping.md
• Threat Dragon export and schema checks: docs/threat-dragon-export-testing.md
• Structurizr export and validation: docs/structurizr-export-testing.md
• TRLC requirements export and validation: docs/trlc-export-testing.md
• TRLC + LOBSTER traceability report pipeline: docs/lobster-traceability.md

System-of-Systems Composition

A model declares exact dependencies in engmod.yml and composes their selected publications from model/architecture.yml.

# engmod.yml
dependencies:
  - alias: telemetry
    path: models.example/coffee-fleet/telemetry@v0
    version: v0.1.0
    publications: [public]

# model/architecture.yml
architecture:
  composition:
    subsystems:
      - id: SUB-TELEMETRY
        name: Machine Telemetry Subsystem
        dependency: telemetry
        publication: public
    allocations:
      - requirement: REQ-COF-001
        to: SUB-TELEMETRY
        target: telemetry::CAP-TELEM-REPORT
        rationale: Reporting is realized by the telemetry subsystem.
    satisfactions:
      - need: ota-agent::NEED-TELEMETRY-FEED
        by: telemetry::CAP-TELEM-REPORT

Dependencies are standard CUE modules fetched from the OCI registry selected by CUE_REGISTRY and materialized under .engmod/modules. A module contains cue.mod/module.cue, engmod.yml, and the eight domain documents:

module: "models.example.com/company/security@v0"
language: version: "v0.17.0"

Publish with the standard CUE workflow:

export CUE_REGISTRY=registry.example.com/company-models
cue mod tidy
cue mod publish v0.3.1

For multi-repository local development, place engmod.work.yml above the repositories. Published coordinates stay unchanged while dependencies resolve from explicit sibling paths:

schemaVersion: 2
replacements:
  - module: models.example.com/company/security@v0
    path: ./repos/security

Replacement paths must remain inside the workspace and their cue.mod/module.cue identity must match. Composition rejects floating or invalid versions, path escapes, cycles, missing manifests, unpublished targets, and unsatisfied requirements.

See examples/coffee-fleet-ota-cloud-sample for local composition and examples/atlas-industries for a seven-repository company portfolio with two products reusing shared hardware/software, security, compliance, and cloud modules through OCI coordinates.

Requirement delegation (no tiers)

Delegation is flat — there are no requirement tiers. A parent requirement is satisfied by delegating it to a subsystem contract entry, expressed as a composition.allocations entry that binds the requirement to a subsystem (target naming the provided contract id within that subsystem). A delegation without a resolvable target raises composition.untraceable_delegation. A delegated requirement counts against the requirement.orphan rollup, so a requirement that is neither implemented in code nor delegated to a subsystem still surfaces as orphaned.

OSCAL chain generation

Use engoscal to generate SSP, Assessment Results, and POA&M artifacts from architecture inputs.

SSP only:

go run ./cmd/engoscal --model examples/payments-engineering-sample/engmod.yml --ssp-out examples/payments-engineering-sample/generated/ARCHITECTURE.ssp.json

Full chain:

go run ./cmd/engoscal \
  --model examples/payments-engineering-sample/engmod.yml \
  --requirements examples/payments-engineering-sample/model/requirements.yml \
  --code-root examples/payments-engineering-sample/src \
  --profile examples/payments-engineering-sample/oscal/profile-nist-800-53-low.json \
  --catalog examples/payments-engineering-sample/oscal/catalog-nist-800-53-rev5-subset.json \
  --ssp-out examples/payments-engineering-sample/generated/ARCHITECTURE.ssp.json \
  --ar-out examples/payments-engineering-sample/generated/ARCHITECTURE.ar.json \
  --poam-out examples/payments-engineering-sample/generated/ARCHITECTURE.poam.json \
  --ap-href ./ASSESSMENT-PLAN.json \
  --ssp-href ./ARCHITECTURE.ssp.json

Validation with OSCAL CLI (containerized):

podman run --rm -v "$PWD":/work:Z -w /work docker.io/matthewruge/oscal-cli:0.2.0 ssp validate --as json examples/payments-engineering-sample/generated/ARCHITECTURE.ssp.json
podman run --rm -v "$PWD":/work:Z -w /work docker.io/matthewruge/oscal-cli:0.2.0 ar validate --as json examples/payments-engineering-sample/generated/ARCHITECTURE.ar.json
podman run --rm -v "$PWD":/work:Z -w /work docker.io/matthewruge/oscal-cli:0.2.0 poam validate --as json examples/payments-engineering-sample/generated/ARCHITECTURE.poam.json

Gemara GRC rendering

Gemara is a first-class rendering of the model: enggemara projects the engineering model into OpenSSF Gemara documents using the official go-gemara SDK types, and every artifact validates against the published Gemara CUE schemas.

All 13 Gemara artifact types are produced:

• L1 Vector Catalog ← attackVectors (with environment applicability)
• L1 Principle Catalog ← standard governance principles
• L1 Guidance Catalog ← control families (control guidelines link back to it)
• L2 Capability Catalog ← functionalUnits (+ a synthetic system capability)
• L2 Threat Catalog ← threatScenarios (capabilities, vectors, and threat actors)
• L2 Control Catalog ← controls + controlVerifications (synthesized assessment-requirements)
• L3 Risk Catalog ← risks (severity derived from likelihood × impact; unique rank)
• L3 Policy ← compliance/risks/controls (scope, imports, risk treatment, adherence)
• L5 Evaluation Log ← controlVerifications (pass and fail, with evidence)
• L6 Enforcement Log ← poamItems (remediation actions)
• L7 Audit Log ← controlVerifications + residual risks
• Mapping Document ← control → threat relationships
• Lexicon ← catalog terms (controlled vocabulary)

Generate the catalogs and logs:

go run ./cmd/enggemara \
  --model examples/payments-engineering-sample/engmod.yml \
  --requirements examples/payments-engineering-sample/model/requirements.yml \
  --out-dir examples/payments-engineering-sample/generated/gemara \
  --version 1.0.0 --date 2026-06-26T00:00:00Z

Optionally emit OSCAL via the Gemara SDK bridge (additive; the hand-written OSCAL SSP/AR/POA&M under engoscal are retained):

go run ./cmd/enggemara --model <engmod.yml> --requirements <model/requirements.yml> \
  --out-dir <dir> \
  --oscal-catalog-out <dir>/oscal-catalog.json \
  --oscal-ar-out <dir>/oscal-ar.json

Validation:

• in-repo, via the go-gemara SDK loader + type discriminator: go test -run TestGemara ./...
• against the official CUE schemas: scripts/validate-gemara.sh (needs the cue CLI and the Gemara schema module; set GEMARA_SCHEMA_DIR to a checkout of github.com/gemaraproj/gemara)

The generated AsciiDoc document includes a Gemara GRC Model chapter, and the MCP server exposes a gemara.* tool per artifact type (gemara.controlCatalog, gemara.threatCatalog, gemara.riskCatalog, gemara.vectorCatalog, gemara.capabilityCatalog, gemara.principleCatalog, gemara.guidanceCatalog, gemara.policy, gemara.lexicon, gemara.mappingDocument, gemara.auditLog, gemara.enforcementLog, gemara.evaluationLog) plus gemara.validate.

See docs/gemara-rendering.md for the field-by-field mapping and the OSCAL decision.

Agent Skills

Use these docs to drive AI-agent development workflows and tagging conventions:

• OpenCode-ready skill (auto-discoverable by opencode debug skill): .opencode/skills/engineering-model-architecture-ai/SKILL.md
• framework-neutral workflow and tagging contract: docs/skills/architecture-mcp-workflow.md
• OpenCode adapter prompt: docs/skills/adapters/opencode-skill-prompt.md
• generic adapter prompt for other frameworks: docs/skills/adapters/generic-agent-prompt.md

Example Project

End-to-end sample inputs and generated outputs are under:

• examples/payments-engineering-sample
• examples/bedrock-pr-review-github-app-sample
• examples/coffee-fleet-ota-cloud-sample

Core files:

• engmod.yml
• model/catalog.yml
• model/requirements.yml
• model/architecture.yml
• model/behavior.yml
• model/assurance.yml
• model/compliance.yml
• model/views.yml
• model/decisions.yml
• infra/terraform
• src (Go/Rust/TypeScript traced code)

Development

Unit checks:

go test ./...
go vet ./...

The canonical validation gauntlet is scripts/validate-all.sh — the single source of truth for both local development and CI:

bash scripts/validate-all.sh

It runs strict gates that always fail the build:

• go build ./...
• generation gates: engdoc exits non-zero on any error (transitively enforcing trace integrity / dangling links, EARS lint, and composition checks)
• engtrace: zero dangling code trace links per model
• artifact freshness: regenerated ARCHITECTURE.adoc / DECISIONS.adoc / TRACE-MATRIX.json must match what is committed (detected via git diff)

plus best-effort gates that run only when their tool is on PATH (a missing tool is skipped, a real failure still fails the build):

• Gemara CUE schema validation (cue)
• Structurizr DSL validation (behind ENGMOD_VALIDATE_STRUCTURIZR=1, via docker/podman)
• TRLC validation (trlc)

.github/workflows/ci.yml runs scripts/validate-all.sh, so the same gates apply in CI.

Generated ARCHITECTURE.adoc, DECISIONS.adoc, and TRACE-MATRIX.json are deterministic and reproducible; CI fails on any drift, so when you change a model you must regenerate these artifacts and commit them alongside the model change.

Contributing

See CONTRIBUTING.md.

License

This project is licensed under the MIT License. See LICENSE.