Three Layers of Organisational Source of Truth in Software Projects

Software teams often talk about having a single source of truth. In practice, a software project rarely has just one.

The source code may tell us exactly what the system does today, but it does not necessarily tell us what the system should do, why certain decisions were made, or whether those decisions comply with the wider organisation’s rules.

A more useful model is to think of software development as operating within three layers of organisational truth:

Code source of truth — what the system actually does.
Project bible — what the project intends, assumes, and has decided.
Organisation governance — what the organisation permits, requires, and standardises.

These layers overlap, but they answer fundamentally different questions.

flowchart TB
    G["Organisation Governance<br/>What are we allowed and required to do?"]
    P["Project Bible<br/>What should this project do and why?"]
    C["Code Source of Truth<br/>What does the system actually do?"]

    G --> P
    P --> C

    C -. "Implementation feedback" .-> P
    P -. "Project feedback" .-> G

The important point is that truth flows downward as constraints and intent, while information also needs to flow upward when implementation exposes assumptions, problems, or new requirements.

1. Code Source of Truth

At the lowest and most concrete level is the codebase.

The repository contains the executable reality of the system:

application code;
configuration;
database migrations;
infrastructure definitions;
API contracts;
automated tests;
dependency definitions;
build and deployment configuration.

If the documentation says that an API endpoint accepts one parameter but the deployed application accepts another, the running code ultimately determines what actually happens.

In that sense, code is the source of truth for implementation.

But this phrase is sometimes stretched too far.

Code is generally very good at answering:

What does the system currently do?

It is much less reliable at answering:

Why does it do this?

Consider a seemingly arbitrary rule:

if (failedAttempts >= 5) {
    lockAccount();
}

The code clearly tells us that five failed attempts result in an account lock.

It does not tell us whether five attempts were chosen because of:

a security policy;
a regulatory requirement;
a product decision;
a historical incident;
a temporary workaround;
or simply a developer’s judgement several years ago.

The implementation is authoritative about behaviour, but not necessarily about intent.

This becomes especially important when someone — human or AI — changes the code.

A developer might reasonably look at that logic and decide that ten attempts would create a better user experience. From a purely technical perspective, the change may be perfectly valid.

From an organisational perspective, it could be completely wrong.

2. The Project Bible

Between organisational policy and source code sits a layer that many projects have informally but few maintain deliberately.

I think of it as the project bible.

This is not simply conventional technical documentation. It is the authoritative body of knowledge describing what the project is supposed to be.

It may include:

architecture principles;
domain terminology;
functional requirements;
important business rules;
design decisions;
architectural decision records;
integration contracts;
security assumptions;
data ownership;
expected system behaviour;
constraints and non-goals;
accepted technical debt;
deployment assumptions;
conventions specific to the project.

For example, imagine an organisation building a multi-tenant SaaS platform.

The code may currently contain:

tenant_id

throughout its database queries.

The project bible should contain the more important rule behind that implementation:

All tenant-owned data must be isolated by tenant at every persistence and service boundary.

That statement survives implementation changes.

The team could move from PostgreSQL row filtering to separate schemas, separate databases, or some future storage architecture. The source code would change substantially, but the project truth would remain: tenant isolation is a fundamental system requirement.

This is what makes the project bible different from generated documentation.

Generated documentation can describe the system.

A project bible helps define the system.

It also records why

Software projects accumulate decisions that are almost invisible when looking only at the finished code.

Perhaps the team evaluated three message brokers and deliberately chose one.

Perhaps a particular service is separate because it has a very different security boundary.

Perhaps an apparently inefficient database structure exists because historical records are legally required to remain immutable.

Without project-level context, future developers can mistake deliberate design decisions for mistakes.

Worse, they may successfully “fix” them.

3. Organisation Governance

Above individual projects sits a third source of truth: the organisation itself.

An engineering team does not operate in isolation.

The organisation may have rules covering:

approved technologies;
cybersecurity;
authentication;
encryption;
data retention;
personally identifiable information;
logging and auditing;
regulatory compliance;
infrastructure providers;
software licensing;
dependency management;
accessibility;
coding standards;
deployment processes;
disaster recovery;
observability;
source-control practices;
change management;
AI usage;
architecture standards.

These rules may apply to dozens or hundreds of projects.

A project team should therefore not duplicate every organisational rule into its own documentation. Instead, the project should inherit applicable governance and document where project-specific decisions refine it.

For example:

Organisation rule:
Customer secrets must never be stored unencrypted.

Project rule:
Integration credentials are stored using the organisation's approved
secrets-management platform.

Implementation:
The application retrieves credentials through the secrets service at runtime.

These are three different statements at three different levels of authority.

They are related, but they are not interchangeable.

The Three Layers Together

A useful way of thinking about the relationship is:

Layer	Primary question	Typical content
Organisation governance	What must or must not we do?	Policy, compliance, standards, approved technologies
Project bible	What should this system do, and why?	Architecture, requirements, decisions, constraints
Code source of truth	What does the system actually do?	Code, configuration, infrastructure, migrations, tests

A healthy project should be able to trace important behaviour through all three layers.

flowchart LR
    A["Governance<br/>Customer data must be encrypted"]
    B["Project Bible<br/>Customer records use approved encryption strategy"]
    C["Code<br/>Encryption implementation and configuration"]
    D["Tests<br/>Verify encrypted storage"]

    A --> B
    B --> C
    C --> D

This traceability becomes particularly valuable when something changes.

The Real Problem Is Divergence

The biggest danger is not missing documentation.

It is contradictory truth.

Suppose organisational governance states:

Production services must use the organisation’s central identity provider.

The project’s architecture documentation agrees.

But six months later, a developer introduces a local authentication mechanism while building a new administration service.

Now the organisation contains three versions of reality:

flowchart TB
    G["Governance<br/>Use central identity provider"]
    P["Project Bible<br/>Authentication uses central identity provider"]
    C["Code<br/>New admin service uses local authentication"]

    G -->|"aligned"| P
    P -->|"DIVERGENCE"| C

Nothing may fail technically.

The application compiles.

The tests pass.

CI is green.

The feature works perfectly.

And the implementation is still wrong.

This is one reason conventional code review alone cannot guarantee organisational correctness.

Source of Truth Is Also About Authority

Once multiple sources of truth exist, another question becomes important:

Which source wins when they disagree?

There should be a hierarchy.

As a general principle:

Organisation governance
        ↓
Project requirements and architecture
        ↓
Implementation

If code contradicts a documented project requirement, either the code needs changing or the requirement needs formally revising.

If the project bible contradicts organisational governance, either the project must change or an explicit exception needs to be approved.

What should not happen is silent divergence.

That distinction matters.

A source of truth is not authoritative because somebody wrote it in Markdown.

It is authoritative because the organisation has agreed that this is where a particular category of decision is defined.

Changes Need to Move in Both Directions

The hierarchy does not mean information only travels downward.

Sometimes implementation teaches us something.

A team may discover that a project requirement is technically impossible, unnecessarily expensive, insecure, or simply based on an incorrect assumption.

The correct response is not to quietly make the code behave differently.

Instead:

flowchart LR
    A["Requirement"]
    B["Implementation"]
    C["Problem discovered"]
    D["Review decision"]
    E["Update Project Bible"]
    F["Update Code"]

    A --> B
    B --> C
    C --> D
    D --> E
    E --> F

The source of truth itself changes first — or as part of the same controlled change.

The implementation then remains aligned with it.

The same principle applies between a project and organisational governance. If enough projects discover that an organisational rule no longer makes sense, perhaps the governance itself needs revision.

Truth should be controlled, but it should not be fossilised.

AI Makes This More Important

AI-assisted software development makes this distinction considerably more important.

An AI coding agent can inspect a repository and become remarkably good at understanding the local implementation.

But the repository may not contain the information required to understand the organisation.

The agent may see:

export async function saveDocument(document: Document) {
    return repository.save(document);
}

and produce a technically excellent enhancement.

What it may not know is:

documents have a seven-year retention requirement;
deletion must be soft deletion;
audit records must be immutable;
a tenant can only access documents belonging to that tenant;
certain document categories cannot leave a particular jurisdiction.

None of those rules can safely be inferred from programming language syntax.

An AI agent therefore needs access to more than code if it is expected to make decisions rather than simply implement tightly specified instructions.

flowchart TB
    AI["Developer / AI Coding Agent"]

    G["Organisation Governance"]
    P["Project Bible"]
    C["Codebase"]

    G --> AI
    P --> AI
    C --> AI

    AI --> R["Proposed Change"]
    R --> V["Validate against all three sources"]

The more autonomous development tooling becomes, the more important context governance becomes.

Otherwise we risk producing code faster than ever while simultaneously increasing the rate at which systems drift away from their intended architecture and organisational rules.

Documentation Alone Does Not Solve It

There is another uncomfortable problem.

Most organisations already have plenty of documentation.

The problem is often discovering:

which document is authoritative;
whether it is current;
whether another document supersedes it;
who owns it;
which projects it applies to;
which rules are mandatory;
whether the implementation still complies with it.

A folder containing 2,000 pages of Confluence documentation is not necessarily a source of truth.

It may simply be a large collection of information.

For something to function as organisational truth, it needs characteristics such as:

clear ownership;
defined authority;
versioning;
scope;
review;
traceability;
controlled change;
discoverability.

Otherwise developers are forced to decide which pieces of documentation they believe.

And an AI agent faces exactly the same problem, only much faster.

Source-of-Truth Validation Should Become Part of Development

This suggests that source-of-truth validation belongs inside the software development lifecycle rather than outside it.

A simplified workflow might look like this:

flowchart TD
    A["Specification / Task"]
    B["Check Organisation Governance"]
    C["Check Project Bible"]
    D["Implement Change"]
    E["Code Review"]
    F["Source-of-Truth Validation"]
    G["Testing"]
    H["Update Documentation if Required"]
    I["Commit / Deploy"]

    A --> B
    B --> C
    C --> D
    D --> E
    E --> F
    F --> G
    G --> H
    H --> I

    F -->|"Conflict found"| C

That validation does not necessarily need to be a bureaucratic manual process.

Some rules can be automated.

A system could detect that:

a prohibited dependency has been introduced;
an API no longer matches its contract;
a database entity violates a tenant-isolation rule;
a new infrastructure resource uses an unapproved provider;
implementation has changed while its associated architectural decision has not;
code contradicts a project-level requirement.

Other decisions still require human judgement.

The objective is not to turn governance into a giant set of linting rules.

It is to make organisational intent visible at the point where software is being changed.

Not One Source of Truth, but a Chain of Truth

The phrase “single source of truth” remains useful, provided we apply it to the right scope.

There can be a single authoritative source for organisational policy.

There can be an authoritative project knowledge base.

There can be an authoritative source repository.

But trying to collapse all three into one thing creates a different problem.

Code should not become the organisation’s policy manual.

Corporate governance should not describe individual implementation details.

And the project bible should not attempt to reproduce every line of code.

A better model is a chain of truth:

flowchart TB
    O["ORGANISATION<br/>Principles, policies, standards and constraints"]
    P["PROJECT<br/>Requirements, architecture, decisions and intent"]
    C["CODE<br/>Actual implementation"]
    R["RUNTIME<br/>Actual behaviour in production"]

    O -->|"governs"| P
    P -->|"defines"| C
    C -->|"produces"| R

    R -. "observations" .-> C
    C -. "changes & discoveries" .-> P
    P -. "exceptions & lessons" .-> O

Each layer has a different responsibility.

Each can change.

Each needs ownership.

And the connections between them matter as much as the individual repositories of information.

When those connections are maintained, a developer can understand not only what the code does, but why it exists and what boundaries it must respect.

That becomes increasingly important as software development moves from humans writing every line themselves toward humans, AI agents, automated tooling, and organisational systems collectively producing software.

The challenge is no longer simply keeping the code correct.

It is keeping the code aligned with the project, and keeping the project aligned with the organisation.