4.1: Source Code as Single Source of Truth

What You'll Learn

By the end of this chapter, you will be able to:

• Explain the "source code as truth" principle
• Design editor-agnostic development workflows
• Configure CI/CD pipelines as the authoritative processing layer
• Avoid editor/IDE lock-in
• Apply source-code-truth to documentation, traceability, and configuration management
• Recognize anti-patterns that erode a single source of truth
• Implement practical workflows for safety-critical projects

The Core Principle

The diagram below shows how source code flows from any editor through the authoritative pipeline, which enforces quality gates regardless of which tool produced the code.

Any editor works. The pipeline is the authority.

What This Means

Source Code Repository

CI/CD Pipeline

Editors/IDEs

Single Source of Truth Principle

In safety-critical systems governed by ASPICE, ISO 26262, or DO-178C, the single source of truth principle is not merely a convenience — it is a compliance requirement. When multiple representations of the same information exist without a clear authoritative source, inconsistencies become inevitable, and inconsistencies in safety-critical systems can lead to hazardous failures.

Principle: Every piece of project information — requirements, design, code, tests, configuration — must have exactly one authoritative location. All other representations are derived from that location and verified against it.

Why Safety-Critical Systems Demand This

The Cost of Duplication

When information lives in two places, one of them is always wrong. In regulated environments, this creates a specific and measurable risk:

• ASPICE SUP.10 (Change Request Management) requires that changes propagate to all affected work products. Duplication makes this exponentially harder.
• ISO 26262 Part 8 Clause 6 requires configuration management of all safety-related work products. Duplicate sources create uncontrolled artifacts.
• DO-178C Section 7 requires that software lifecycle data be controlled. Shadow copies violate this requirement.

Documentation as Code

The documentation-as-code approach treats documentation with the same rigor applied to source code: it is version-controlled, reviewed, tested, and deployed through the same pipeline.

Key Insight: If documentation does not live in the repository, it will drift from the code it describes. If it does not pass through the pipeline, its quality is unverified.

Core Practices

CI/CD for Documentation

A documentation pipeline should enforce the same quality gates as a code pipeline:

# Example documentation pipeline stage
doc_quality:
  stage: verify
  script:
    - markdownlint docs/**/*.md
    - check-links docs/**/*.md
    - verify-traceability --requirements docs/requirements/ --tests test/
    - build-docs --format pdf --output output/
  artifacts:
    paths:
      - output/*.pdf

What Belongs in the Repository

AI and Documentation Drift

AI-generated content introduces a new category of documentation drift. When an AI tool generates or updates documentation, the output may be plausible but subtly wrong — and because it reads well, human reviewers may not catch the inaccuracies.

Warning: AI-generated documentation that is not verified against the actual source code is a liability, not an asset. Plausible-sounding text that contradicts the implementation is worse than no documentation at all.

How Drift Occurs

Mitigation Strategies

The HITL Requirement for AI Documentation

In safety-critical contexts, AI-generated documentation must follow the same HITL (Human-in-the-Loop) pattern as AI-generated code:

1. AI generates or updates documentation
2. Pipeline validates structural correctness
3. Human reviews content accuracy
4. Approved documentation is merged to the authoritative branch
5. Pipeline builds and publishes derived artifacts

Skipping step 3 is never acceptable for safety-related work products.

Traceability from Source

ASPICE requires bidirectional traceability across all engineering levels. The single source of truth principle enables this by ensuring that every traceable link points to exactly one canonical location.

Traceability Chain

Implementing Traceability in Source

Traceability identifiers can be embedded directly in source code, keeping the link alive at the point of truth:

/**
 * @requirement SWR-042
 * @design SDD-017
 * @safety ASIL-B
 *
 * Calculate braking distance based on current velocity and
 * road surface coefficient.
 */
float calculate_braking_distance(float velocity, float surface_coeff)
{
    /* Implementation */
}

# test_braking.py
class TestBrakingDistance:
    """
    Verifies: SWR-042
    Design Ref: SDD-017
    """
    def test_dry_road(self):
        assert calculate_braking_distance(30.0, 0.8) < 45.0

Pipeline-Enforced Traceability

The CI/CD pipeline can verify that traceability is complete:

traceability_check:
  - Parse all @requirement tags from source code
  - Parse all Verifies: tags from test code
  - Cross-reference against requirements database
  - Report: uncovered requirements, orphaned tests, broken links
  - Quality gate: FAIL if any requirement lacks both implementation and test

Configuration Management

The single source of truth principle is the foundation of ASPICE SUP.8 (Configuration Management). When all project artifacts are derived from or controlled within the repository, configuration management becomes tractable rather than heroic.

SUP.8 Base Practices and Source Code Truth

Configuration Items in the Repository

Principle: If an artifact cannot be reconstructed from a tagged commit in the repository, it is not under proper configuration management.

Editor-Agnostic Workflow

Recommended Architecture

The following diagram shows the recommended separation between developer workstations (where editing happens) and the CI/CD pipeline (where enforcement happens), with the repository as the handoff point.

What Goes Where

Practical Implementation

Repository Structure

project/
├── src/                     # Source code
├── include/                 # Headers
├── test/                    # Test code
├── docs/                    # Documentation
├── config/
│   ├── .clang-format       # Code style (used by pipeline)
│   ├── .clang-tidy         # Static analysis rules
│   ├── sonar-project.properties  # SonarQube config
│   └── misra.rules         # MISRA configuration
├── ci/
│   ├── Jenkinsfile         # Pipeline definition
│   ├── build.sh            # Build script
│   └── quality-gate.sh     # Quality enforcement
├── .editorconfig           # Cross-editor formatting
└── README.md

.editorconfig Example

# Cross-editor settings
root = true

[*]
indent_style = space
indent_size = 4
end_of_line = lf
charset = utf-8
trim_trailing_whitespace = true
insert_final_newline = true

[*.c]
indent_size = 4

[*.py]
indent_size = 4

[Makefile]
indent_style = tab

AI Integration Pattern

Editor-Local AI

Pipeline AI

The following diagram contrasts the boundary between local AI assistance (advisory, no authority) and pipeline AI analysis (authoritative, with enforcement power).

Living Documentation Architecture

Keeping documentation in sync with source code requires more than good intentions. It requires a technical architecture that makes drift detectable and correctness verifiable.

Architecture Components

Sync Verification Approach

The pipeline should verify documentation freshness on every commit:

doc_sync_check:
  steps:
    - Extract public API signatures from source code
    - Extract documented API signatures from docs
    - Compare: flag any undocumented public APIs
    - Compare: flag any documented APIs that no longer exist
    - Verify all requirement tags in code have matching entries in requirements docs
    - Verify all test tags reference valid requirements
    - FAIL if discrepancies exceed threshold

Freshness Policy

AI Documentation Agents

AI agents can be deployed to monitor and maintain documentation quality, operating within the HITL framework required by safety standards.

Principle: AI documentation agents propose changes; humans approve them. The agent never writes directly to the authoritative branch.

Agent Roles

Agent Workflow

1. Trigger: Code change is pushed or scheduled job fires
2. Analysis: Agent compares code state against documentation state
3. Report: Agent generates a structured report of discrepancies
4. Proposal: Agent opens a draft pull request with suggested documentation updates
5. Review: Human reviewer evaluates proposals for accuracy
6. Merge: Approved changes are merged to the authoritative branch

Guardrails for AI Documentation Agents

Markdown as Standard

For safety-critical documentation managed as code, Markdown has emerged as the practical standard. Its simplicity is its strength.

Why Markdown Works

Markdown Limitations and Mitigations

Structured Markdown for Requirements

Requirements can be captured in Markdown with structured metadata:

### SWR-042: Braking Distance Calculation

| Field | Value |
|-------|-------|
| ID | SWR-042 |
| Priority | Mandatory |
| ASIL | B |
| Parent | SYS-REQ-018 |
| Status | Approved |
| Version | 1.2 |

**Description**: The system shall calculate braking distance based on
current vehicle velocity and road surface friction coefficient.

**Rationale**: Required for forward collision warning activation threshold.

**Acceptance Criteria**:
- Braking distance is computed within 10ms of velocity update
- Accuracy within 5% of physics-based reference model
- Handles surface coefficients in range [0.1, 1.0]

Practical Workflow

The following step-by-step workflow illustrates how to maintain source code truth on a daily basis in a safety-critical project.

Step 1: All Changes Start in the Repository

Every modification — code, documentation, configuration, test — begins as a change in the version-controlled repository. No changes are made in external tools and then "synced back."

Step 2: Branch and Link

Create a feature branch linked to a requirement or change request:

git checkout -b feature/SWR-042-braking-distance

The branch name encodes traceability. The pull request description references the requirement ID.

Step 3: Implement with Embedded Traceability

Write code with requirement and design tags embedded. Write or update documentation in the same branch. Write or update tests that reference the same requirement.

Step 4: Pipeline Validates

On push, the CI/CD pipeline:

Step 5: Review

Human reviewers verify:

• Code correctness and safety implications
• Documentation accuracy
• Traceability completeness
• AI-generated content (if any) is factually correct

Step 6: Merge to Authoritative Branch

After approval, the branch is merged. The authoritative branch now contains the updated code, documentation, tests, and traceability — all in one atomic change.

Step 7: Baseline

At release milestones, the authoritative branch is tagged. This tag constitutes a baseline: a complete, consistent, traceable snapshot of the entire project state.

Benefits

Team Flexibility

• Developers choose preferred editors
• New team members use familiar tools
• No training on specific IDE

Vendor Independence

• No lock-in to specific IDE vendor
• Switch AI tools without disruption
• Upgrade/replace tools independently

Process Stability

• Pipeline changes independent of editors
• Quality standards enforced consistently
• Reproducible results

AI Portability

• AI tools can be changed
• Compare AI assistants easily
• Future AI tools integrate simply

Anti-Patterns

The following anti-patterns undermine the single source of truth and create risk in safety-critical projects.

Implementation Checklist

Use this checklist when establishing or auditing source-code-truth practices on a project.

Summary

The "source code as single source of truth" principle:

1. Repository is authority: Source code is the definitive artifact
2. Pipeline processes: CI/CD is the authoritative processing layer
3. Editors are interfaces: Any editor can be used
4. AI serves code: AI tools assist with source, not replace it
5. No lock-in: Technology can change without process disruption
6. Documentation lives with code: Docs-as-code prevents drift
7. Traceability is embedded: Links from requirements to tests live in source
8. Configuration management follows naturally: SUP.8 compliance is built-in when the repo is the single source
9. AI agents assist, humans decide: Documentation agents propose; humans approve
10. Anti-patterns are identifiable: Knowing what breaks the principle helps prevent it