architecture

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

May 28, 2026 Chachamaru127/claude-code-harness ↗

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 at the repository root. This file serves as the authoritative specification for the entire project.

Settings and Safety Policies

Configuration and safety policies are governed by harness.toml, which acts as the declarative source for all harness settings.

  • Mirrors: Generated settings.json (produced via bin/harness sync) and template baselines in templates/...
  • Enforcement: tests/test-settings-baseline.sh verifies that counts such as deniedDomains in 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.

Memory and Decisions

The decision log at .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.

Enforcement Mechanisms

Four distinct mechanisms guarantee SSOT integrity throughout the development lifecycle:

  1. Synchronization Scripts: 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, test-settings-baseline.sh, and 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 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 under the "## SSOT (Single Source of Truth)" section and in 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:


# 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 or 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:


# 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:


# 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 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 and bin/harness sync propagate changes to read-only mirrors
  • CI enforcement: Tests such as test-spec-ssot-workflow.sh and 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 and 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 and 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 under the "## SSOT (Single Source of Truth)" heading and in 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 for product contracts, tests/test-settings-baseline.sh for harness.toml integrity, and tests/test-skill-design-contract.sh for routing rules. Additionally, scripts/ci/check-consistency.sh and ./tests/validate-plugin.sh provide aggregate validation across all SSOT domains during continuous integration.

Have a question about this repo?

These articles cover the highlights, but your codebase questions are specific. Give your agent direct access to the source. Share this with your agent to get started:

Share the following with your agent to get started:
curl -s "https://instagit.com/install.md"
Works with
Claude Codex Cursor VS Code OpenClaw Any MCP Client

Maintain an open-source project? Get it listed too →