# SSOT Pattern in claude-code-harness: Architecture and Enforcement

> Learn the SSOT pattern in claude-code-harness. Discover how configuration, contracts, and policies are managed with automated synchronization and CI validation for a single source of truth.

- Repository: [Chachamaru/claude-code-harness](https://github.com/Chachamaru127/claude-code-harness)
- Tags: architecture
- Published: 2026-05-28

---

**The SSOT (Single Source of Truth) pattern in claude-code-harness guarantees that every configuration, contract, and policy lives in exactly one canonical file per domain, with automated synchronization and CI validation ensuring all mirrors remain identical to their authoritative sources.**

The `Chachamaru127/claude-code-harness` repository implements a rigorous SSOT architecture to prevent configuration drift across its multi-agent ecosystem. By establishing read-only constraints for agents and mandatory promotion workflows for any SSOT modifications, the codebase ensures that both human developers and autonomous Claude agents operate against consistent, authoritative data derived from single canonical sources.

## What Is the SSOT Pattern?

The **SSOT (Single Source of Truth)** pattern is a set of architectural conventions that designate exactly one file as the authoritative source for each domain of knowledge. In `claude-code-harness`, this means that downstream locations—such as agent memory layers, generated JSON files, or documentation mirrors—are treated as **deterministic projections** of their canonical sources rather than editable copies. Any divergence between the source and its mirrors triggers immediate CI failures, creating a self-checking system where the repository state is always consistent.

## Canonical Sources and Their Mirrors

The repository defines five primary SSOT domains, each with a designated canonical file, dependent mirrors, and specific enforcement mechanisms.

### Product Contract

The **product contract** resides in [`spec.md`](https://github.com/Chachamaru127/claude-code-harness/blob/main/spec.md) at the repository root. This file serves as the authoritative specification for the entire project.

- **Mirrors**: [`Plans.md`](https://github.com/Chachamaru127/claude-code-harness/blob/main/Plans.md), architectural sub-specs ([`docs/architecture/hokage-core.md`](https://github.com/Chachamaru127/claude-code-harness/blob/main/docs/architecture/hokage-core.md)), and language-specific specs ([`go/SPEC.md`](https://github.com/Chachamaru127/claude-code-harness/blob/main/go/SPEC.md))
- **Enforcement**: [`tests/test-spec-ssot-workflow.sh`](https://github.com/Chachamaru127/claude-code-harness/blob/main/tests/test-spec-ssot-workflow.sh) asserts that [`spec.md`](https://github.com/Chachamaru127/claude-code-harness/blob/main/spec.md) is the authoritative contract and validates that mirrors contain identical content

### Settings and Safety Policies

**Configuration and safety policies** are governed by [`harness.toml`](https://github.com/Chachamaru127/claude-code-harness/blob/main/harness.toml), which acts as the declarative source for all harness settings.

- **Mirrors**: Generated [`settings.json`](https://github.com/Chachamaru127/claude-code-harness/blob/main/settings.json) (produced via `bin/harness sync`) and template baselines in `templates/...`
- **Enforcement**: [`tests/test-settings-baseline.sh`](https://github.com/Chachamaru127/claude-code-harness/blob/main/tests/test-settings-baseline.sh) verifies that counts such as `deniedDomains` in [`harness.toml`](https://github.com/Chachamaru127/claude-code-harness/blob/main/harness.toml) match the generated JSON; the `bin/harness sync` command prints drift warnings when files diverge

### Skill Routing Rules

**Routing logic** for skill dispatch is controlled by [`skills/routing-rules.md`](https://github.com/Chachamaru127/claude-code-harness/blob/main/skills/routing-rules.md).

- **Mirrors**: [`codex/.codex/skills/routing-rules.md`](https://github.com/Chachamaru127/claude-code-harness/blob/main/codex/.codex/skills/routing-rules.md) and [`opencode/skills/routing-rules.md`](https://github.com/Chachamaru127/claude-code-harness/blob/main/opencode/skills/routing-rules.md)
- **Enforcement**: [`scripts/sync-skill-mirrors.sh`](https://github.com/Chachamaru127/claude-code-harness/blob/main/scripts/sync-skill-mirrors.sh) propagates changes across mirrors and fails CI if diffs are detected; [`tests/test-skill-design-contract.sh`](https://github.com/Chachamaru127/claude-code-harness/blob/main/tests/test-skill-design-contract.sh) validates the contract syntax

### Memory and Decisions

The **decision log** at [`.claude/memory/decisions.md`](https://github.com/Chachamaru127/claude-code-harness/blob/main/.claude/memory/decisions.md) functions as a read-only SSOT for historical choices and architectural decisions.

- **Mirrors**: Agent-level memory layers and UI displays
- **Enforcement**: The memory layer is read-only for agents; promotion to SSOT requires explicit invocation of the `memory` or `sync-ssot-from-memory` skills, ensuring controlled write paths

### Skill Specifications

Individual **skill definitions** reside in `skills/*/SKILL.md` files, with each skill directory containing its own authoritative specification.

- **Mirrors**: Corresponding files in `codex/.codex/skills/*/SKILL.md` and `opencode/skills/*/SKILL.md`
- **Enforcement**: [`scripts/sync-skill-mirrors.sh`](https://github.com/Chachamaru127/claude-code-harness/blob/main/scripts/sync-skill-mirrors.sh) ensures identical copies; governance tests including [`test-harness-review-governance.sh`](https://github.com/Chachamaru127/claude-code-harness/blob/main/test-harness-review-governance.sh) and [`test-harness-release-governance.sh`](https://github.com/Chachamaru127/claude-code-harness/blob/main/test-harness-release-governance.sh) scan for required contract strings in each mirror

## Enforcement Mechanisms

Four distinct mechanisms guarantee SSOT integrity throughout the development lifecycle:

1. **Synchronization Scripts**: [`scripts/sync-skill-mirrors.sh`](https://github.com/Chachamaru127/claude-code-harness/blob/main/scripts/sync-skill-mirrors.sh) executes automatically after changes to shared SSOT files, copying canonical sources to all mirror locations and aborting CI runs if drift is detected

2. **Validation Tests**: A comprehensive test suite—including [`test-spec-ssot-workflow.sh`](https://github.com/Chachamaru127/claude-code-harness/blob/main/test-spec-ssot-workflow.sh), [`test-settings-baseline.sh`](https://github.com/Chachamaru127/claude-code-harness/blob/main/test-settings-baseline.sh), and [`test-skill-design-contract.sh`](https://github.com/Chachamaru127/claude-code-harness/blob/main/test-skill-design-contract.sh)—runs in CI to verify byte-for-byte equality between sources and mirrors

3. **Declarative Guardrails**: Access controls in [`harness.toml`](https://github.com/Chachamaru127/claude-code-harness/blob/main/harness.toml) and the memory layer restrict agents to read-only operations against SSOT files; write operations must route through promotion skills, preventing accidental divergence during autonomous operation

4. **Pattern Documentation**: The SSOT concept is formally defined in [`CLAUDE.md`](https://github.com/Chachamaru127/claude-code-harness/blob/main/CLAUDE.md) under the "## SSOT (Single Source of Truth)" section and in [`spec.md`](https://github.com/Chachamaru127/claude-code-harness/blob/main/spec.md) under "## SSOT Layers", making the architecture explicit to both developers and autonomous agents

## Practical SSOT Workflows

### Updating the Product Contract

When modifying the authoritative specification, validate changes against the SSOT test suite before committing:

```bash

# Edit the canonical spec

vim spec.md

# Run the spec-SSOT test locally

bash tests/test-spec-ssot-workflow.sh

```

The test fails if downstream files such as [`Plans.md`](https://github.com/Chachamaru127/claude-code-harness/blob/main/Plans.md) or [`go/SPEC.md`](https://github.com/Chachamaru127/claude-code-harness/blob/main/go/SPEC.md) are out of date, requiring synchronization before CI will pass.

### Synchronizing Routing Rules

After editing skill routing logic, propagate changes through the mirror network:

```bash

# Edit the authoritative routing rules

vim skills/routing-rules.md

# Propagate to all mirrors

bash scripts/sync-skill-mirrors.sh

# Verify equality (script fails CI if diffs exist)

git diff --quiet skills/routing-rules.md codex/.codex/skills/routing-rules.md \
  && git diff --quiet skills/routing-rules.md opencode/skills/routing-rules.md

```

### Promoting Decisions from Memory

Agents promote provisional decisions to SSOT using the dedicated skill:

```bash

# Invoke SSOT promotion (agents use this, not manual edits)

cc run memory sync-ssot-from-memory --decision "Enable new sandbox allowlist"

```

This skill reads from [`.claude/memory/decisions.md`](https://github.com/Chachamaru127/claude-code-harness/blob/main/.claude/memory/decisions.md) and writes the authoritative entry into the appropriate SSOT file, ensuring all modifications traverse the governed promotion path.

## Summary

- **Single canonical files**: Each domain (contracts, settings, routing, memory, skills) maintains exactly one editable source file
- **Automatic synchronization**: [`scripts/sync-skill-mirrors.sh`](https://github.com/Chachamaru127/claude-code-harness/blob/main/scripts/sync-skill-mirrors.sh) and `bin/harness sync` propagate changes to read-only mirrors
- **CI enforcement**: Tests such as [`test-spec-ssot-workflow.sh`](https://github.com/Chachamaru127/claude-code-harness/blob/main/test-spec-ssot-workflow.sh) and [`test-settings-baseline.sh`](https://github.com/Chachamaru127/claude-code-harness/blob/main/test-settings-baseline.sh) treat drift as build failures
- **Agent constraints**: Agents cannot write directly to SSOT; they must use promotion skills (`memory`, `sync-ssot-from-memory`)
- **Documentation**: Architecture defined in [`CLAUDE.md`](https://github.com/Chachamaru127/claude-code-harness/blob/main/CLAUDE.md) and [`spec.md`](https://github.com/Chachamaru127/claude-code-harness/blob/main/spec.md) makes the pattern discoverable for autonomous agents

## Frequently Asked Questions

### What happens if I edit a mirror file instead of the canonical source?

CI will fail during the validation phase. Tests such as [`test-spec-ssot-workflow.sh`](https://github.com/Chachamaru127/claude-code-harness/blob/main/test-spec-ssot-workflow.sh) and [`test-skill-design-contract.sh`](https://github.com/Chachamaru127/claude-code-harness/blob/main/test-skill-design-contract.sh) detect byte-level differences between canonical files and their mirrors, blocking merges until the edit is moved to the authoritative source and synchronization is executed.

### How do agents write to SSOT files if the memory layer is read-only?

Agents must invoke promotion skills such as `cc run memory sync-ssot-from-memory` or use the `memory` skill framework. These skills provide the only write path to SSOT files, ensuring that all changes are intentional, logged, and immediately validated against the synchronization requirements.

### Which files define the SSOT architecture for the repository?

The pattern is formally documented in [`CLAUDE.md`](https://github.com/Chachamaru127/claude-code-harness/blob/main/CLAUDE.md) under the "## SSOT (Single Source of Truth)" heading and in [`spec.md`](https://github.com/Chachamaru127/claude-code-harness/blob/main/spec.md) under "## SSOT Layers". These files serve as the conceptual SSOT for the SSOT implementation itself, describing the domain boundaries and enforcement philosophy to both developers and autonomous agents.

### What tests validate that mirrors match their canonical sources?

The repository runs [`tests/test-spec-ssot-workflow.sh`](https://github.com/Chachamaru127/claude-code-harness/blob/main/tests/test-spec-ssot-workflow.sh) for product contracts, [`tests/test-settings-baseline.sh`](https://github.com/Chachamaru127/claude-code-harness/blob/main/tests/test-settings-baseline.sh) for [`harness.toml`](https://github.com/Chachamaru127/claude-code-harness/blob/main/harness.toml) integrity, and [`tests/test-skill-design-contract.sh`](https://github.com/Chachamaru127/claude-code-harness/blob/main/tests/test-skill-design-contract.sh) for routing rules. Additionally, [`scripts/ci/check-consistency.sh`](https://github.com/Chachamaru127/claude-code-harness/blob/main/scripts/ci/check-consistency.sh) and [`./tests/validate-plugin.sh`](https://github.com/Chachamaru127/claude-code-harness/blob/main/./tests/validate-plugin.sh) provide aggregate validation across all SSOT domains during continuous integration.