The upper layers are closer to why the product exists and what the team promises. They change less often, and changes there require more care.

The lower layers are closer to how the system works and how it is proven. They change more often, and depend more heavily on automation and evidence.

One Top-Level Model

The SSOT Nine-Layer Pyramid must be the team's single top-level model for understanding and discussing any long-lived system fact.

Specialized document families can still exist: architecture, working plans, operations, UI, testing, security, support, and release. But they cannot become parallel top-level truth systems.

Every specialized document must state:

• Layer owner: which pyramid layer primarily owns it.
• Feeds / Affects: which layers it informs or changes.
• Stability: whether it is stable fact, current work, evidence, or design reference.
• Exit / Promotion: if temporary, where its stable conclusion moves when it is done.

Without this, a team quickly accumulates competing frameworks:

• The architecture docs say one thing.
• The product roadmap says another.
• The testing docs say another.
• Release notes say another.
• Meeting notes add another.

Humans read these inconsistently. AI synthesizes the wrong answer.

Reading Must Be Top-Down

Anyone, human or AI, must understand a problem top-down:

1. Confirm the mission.
2. Confirm the current strategy.
3. Confirm the promise.
4. Confirm the real Flow.
5. Confirm the domain model.
6. Confirm the system boundary.
7. Confirm the contract.
8. Only then inspect implementation and evidence.

This prevents the team from using local code details to redefine the product. It also prevents AI from reading one nearby file and assuming it represents the global system.

For product, operations, sales, and customer support, the same rule prevents old proposals, stale release notes, or legacy troubleshooting paths from being mistaken for current strategy or current promise.

Useful rules of thumb:

• If a page still exists, that does not mean it is still strategic.
• If an API still exists, that does not mean it is still a user promise.
• If a test still runs, that does not mean it protects the current mainline.
• If a POC works, that does not mean it is a product capability.

Every local fact must first be positioned inside the pyramid.

Updating Must Be Bottom-Up

Every change must land bottom-up:

1. Update code, scripts, database, config, and automation.
2. Update tests, logs, status checks, and release evidence.
3. If implementation changes an executable contract, update the contract layer.
4. If a contract changes component ownership, state ownership, or cross-boundary calls, update boundary and domain model.
5. If domain or boundary changes affect what users, AI agents, operators, customer support, sales, or developers can rely on, update Flow and promise.
6. If promise changes affect resource allocation or long-term product identity, update strategy and mission.

Only update upper layers when lower-layer change truly changes upper-layer meaning.

This rule prevents a small script, one demo, or a temporary customer request from being prematurely promoted into strategy.

Anti-Patterns and Correct Moves

These are not rare accidents. They are the everyday ways complex teams split truth.

The shared failure is that local facts were never positioned inside the pyramid. The solution is not simply "communicate more." Each change must answer three questions: which layer changes, what kind of fact changes in that layer, and what evidence proves the change is complete.

Figure: not every bottom-layer fact should be promoted. Only facts that change evidence, contract, boundary, domain, Flow, promise, strategy, or mission move upward.

Upper Layers Constrain Lower Layers; Lower Layers Prove Upper Layers

Upper layers are not wish lists. Lower layers are not free-form implementation.

Mission constrains strategy. Strategy constrains promise. Promise constrains Flow. Flow constrains domain model. Domain model constrains system boundary. System boundary constrains contract. Contract constrains implementation. Implementation must be proven by evidence.

In the other direction, lower layers must not merely exist. They must prove the upper layers. Implementation details support contracts through tests, logs, status checks, and release evidence. Contracts and evidence support boundary, domain model, Flow, promise, and strategy.

If a public promise has no evidence, it is not a promise. It is a wish.

Every Layer Needs Its Own Entry

Each layer should have its own document or directory entry. Do not put all long-form content into one giant overview.

The overview explains the model and the reading path. It should not become a second source of truth for every layer.

A minimal structure can look like this:

docs/
  README.md
  L1-mission/
  L2-strategy/
  L3-promise/
  L4-flow/
  L5-domain-model/
  L6-system-boundary/
  L7-contract/
  L8-implementation/
  L9-evidence/
  working-plan/
  architecture/
  operations/
  testing/

The exact folder names do not matter. The ownership structure does.

Current Work and Stable Fact Must Be Separate

Stable facts belong in their layer, or in a specialized document owned by that layer.

Temporary plans, investigations, and unresolved tasks belong in a current-work area. They must state the current problem, owner, next closing action, and deletion condition.

When the plan is complete and evidence closes the loop, promote only the stable conclusion to the correct layer. Then delete or compress the plan.

Do not let completed plans, historical logs, and stale checklists remain in the main reading path.

If Documents Conflict, Find the SSOT First

If two documents conflict, first find the explicit SSOT.

If no explicit SSOT exists, a practical temporary rule is to prefer the newer document that sits closer to the fact source. But that is only a triage rule, not a governance model. The durable fix is to create the SSOT and turn conflicting documents into links, references, or deletions.

Be especially strict with words like:

• current focus
• current priority
• core capability
• supported
• released
• mainline
• paused
• candidate
• legacy

If these words are copied across multiple documents, they naturally create split-brain for humans and AI.

Entries, Paths, and Concepts Should Converge

Modules, workflows, commands, documents, and governance entry points should converge by default. They should not naturally grow into many parallel paths.

Any new entry, path, or concept must answer:

• Why can the existing SSOT not carry this?
• Who triggers it?
• What evidence proves it?
• Can CICD or AI execute or verify it?

The same type of work should have only a small number of accurately named entry points. Old aliases, temporary paths, and stale concepts should be deleted or renamed instead of preserved "just in case."

Humans Should Handle Human Work

Humans should focus on goals, scope, business approval, permission authorization, real cost decisions, and final judgment.

Routine execution, verification selection, evidence collection, release progression, and governance checks should default to CICD or AI.

AI agents are not only executors. They should actively detect cognitive load, duplicate entry points, manual steps, and automation gaps, then propose how the system can require less explicit human instruction.

But workflow optimization changes default team behavior. It needs explicit approval first. After approval, contract, implementation, documentation, and evidence must be synchronized.

Every Fact Should Reduce Cognitive Load

A fact deserves long-term documentation only if it reduces future cognitive load for humans and AI.

Long-lived documents should describe current truth. They should not replay useless history. History belongs in explicit logs, release evidence, audit records, or current-work plans.

Good documentation lets a first-time reader understand the latest state quickly. It should not force the reader to reconstruct the entire evolution of the system.

Evidence Is Not Documentation

Documentation can describe a fact. Documentation is not evidence.

Evidence includes:

• tests
• logs
• status commands
• read-only production checks
• release checklists
• approvals
• release evidence
• real provider or real user-path acceptance

If a public promise has no evidence, it is not a promise. It is a wish.

Repository Coverage Starts From Bottom-Layer Facts

Building an SSOT Nine-Layer Pyramid does not mean copying every file into the nine-layer docs.

Start by inventorying bottom-layer facts:

1. What code, scripts, workflows, schemas, submodules, local config, vendor references, and temporary assets exist?
2. What evidence supports them: tests, smoke checks, release evidence, status commands, provider health, or only inventory?
3. Which facts change contracts?
4. Which contracts change boundaries or domain model?
5. Which domain or boundary changes affect Flow or promise?
6. Which promises change strategy or mission?

The pyramid does not seek "documentation coverage for every detail." It seeks ownership and promotion paths for every important surface.

Check Documentation at the End of Every Task

After every development, release, investigation, or documentation task, check:

• Did any stable fact change?
• Did any current plan close?
• Did any promise expand or shrink?
• Did Flow, domain, boundary, contract, implementation, or evidence change?
• Should any old document be deleted, compressed, linked, or renamed?

Documentation must continuously reflect current truth. Otherwise it quickly stops being SSOT and becomes noise.

Minimal Adoption Checklist

If your team wants to adopt the SSOT Nine-Layer Pyramid, start here:

1. Create nine layer entries. They can be short at first, but every layer needs ownership.
2. Create one current-work SSOT for open work only.
3. Remove or link copied statements like "current priority," "current focus," and "core capability."
4. Add Layer owner, Feeds / Affects, Stability, and Exit / Promotion to specialized documents.
5. Define evidence levels: inventory, contract read, static evidence, runtime evidence, release evidence.
6. Converge test, release, and operations entry points into a small number of commands.
7. Give product, operations, sales, and support one path to current promise, Flow, and evidence.
8. Give AI agents a reading order: nine-layer model first, specialized documents second, code third.
9. Give AI agents an updating order: implementation and evidence first, then promote only when meaning changes.
10. At the end of every task, check whether documents need deletion, compression, promotion, or renaming.
11. Clean completed plans regularly so the current-work area does not become a historical archive.

Relationship to the SSOT Essay

The companion essay explains why software engineering principles collapse into SSOT, and why complex teams fail when truth splits:

SSOT: Why Every Software Engineering Principle Is Really About One Thing

This article gives the reusable construction method for the pyramid itself.

The exact directory names are not the point. The point is that the team continuously maintains one current, unique, evidence-backed model of business, product, and engineering truth.