Sync behavior

Complete technical reference for AlignTrue’s sync system. This document is the source of truth for what AlignTrue actually does—no marketing, no aspirations, just the real behavior.

Rule management

AlignTrue uses unidirectional sync: edit files in .aligntrue/rules/, run sync, and changes flow to all configured agents.

When you run aligntrue sync:

Load config from .aligntrue/config.yaml
Load rules from .aligntrue/rules/*.md (your source of truth)
Detect edits by checking modification times (mtime)
Create safety backup (always, unless --dry-run) - backs up rules and agent files
Merge to IR - rules load into an in-memory IR (no separate IR file on disk)
Export to all agents - IR syncs to Cursor, AGENTS.md, VS Code, etc. (read-only exports)
Regenerate lockfile in team mode after exports (skipped on --dry-run)
Done - no interaction required

Key facts:

✅ Single source of truth (your .aligntrue/rules/ directory)
✅ One-way sync (rules directory → IR → exports)
✅ Agent files are read-only with warning comments
✅ Works in both solo and team mode
✅ Clear ownership, no conflicts
❌ Editing agent files does not sync back (correct behavior - they are exports)

How unidirectional sync works

Your workflow:

You edit files in .aligntrue/rules/ (e.g., global.md, backend.md, testing.md)
Run aligntrue sync
Changes flow from rules directory → internal IR → all configured agents
All other formats (Cursor, AGENTS.md, etc.) are read-only exports

One-way flow:


.aligntrue/rules/*.md → in-memory IR → all configured agents (read-only)

Why unidirectional?

Single source of truth prevents conflicts
Clear ownership - you know who edited what
Predictable behavior - same edits produce same results every time
Perfect for teams - pairs with team mode for approval workflows
No bidirectional sync confusion

Configuration examples

Solo developer with rules directory


# .aligntrue/config.yaml
mode: solo
sources:
  - type: local
    path: .aligntrue/rules
exporters:
  - cursor
  - agents

Edit .aligntrue/rules/global.md, run aligntrue sync, changes export to all agents.

Team mode with rules directory


# .aligntrue/config.yaml
mode: team
modules:
  lockfile: true
sources:
  - type: local
    path: .aligntrue/rules
exporters:
  - cursor
  - agents

Edit .aligntrue/rules/ → lockfile is regenerated on sync; enforce drift in CI with aligntrue drift --gates.

Common sync scenarios

1. Solo developer editing local rules


# Edit your rules
nano .aligntrue/rules/global.md
nano .aligntrue/rules/backend.md
 
# Sync to all agents
aligntrue sync

Result: Changes synced to all configured agents (Cursor, AGENTS.md, etc.) within seconds.

2. Team editing with lockfile approval


# Edit rules
nano .aligntrue/rules/global.md
 
# Sync detects changes
aligntrue sync
# ◇ Detected 1 edited file(s)
# ◇ Merging changes from rules
# ✓ Merged changes to IR
# ✓ Lockfile updated
# ✓ Synced to: .cursor/rules/*.mdc, AGENTS.md

Flow:

Changes merge to IR
Lockfile regenerated with new bundle hash
Use aligntrue drift --gates in CI to enforce lockfile validation

Technical details: rule loading and merging

How rule loading works


// Pseudo-code
function loadRules(cwd, config) {
  const rulesDir = ".aligntrue/rules";
  const rules = [];
 
  // Load all *.md files
  const files = glob(`${rulesDir}/*.md`);
  for (const file of files) {
    const parsed = parseMarkdown(file);
    rules.push(...parsed.sections);
  }
 
  return rules;
}

Important: Every sync reads all rule files from .aligntrue/rules/ to ensure IR matches your intent.

How merging works

When you have multiple files in .aligntrue/rules/ (e.g., global.md, backend.md, testing.md), they are merged into the IR:

Parse all *.md files in .aligntrue/rules/
Collect all sections from all files
Update IR with the latest content

Files are loaded in alphabetical order for determinism.

Overview

AlignTrue synchronizes rules between three locations:

Rules Directory - .aligntrue/rules/*.md (your editable source, natural markdown with YAML frontmatter)
Intermediate Representation (IR) - in-memory during sync (merged rules, section fingerprints; not written to disk)
Team artifact - .aligntrue/lock.json (team mode only, bundle hash over team rules + team config)

The sync engine maintains consistency with one-way flow from rules directory to all exports.

Sync directions

Rules directory → IR → agents (default)

When: Every aligntrue sync command (default direction)

Flow:


Rules Directory (.aligntrue/rules/*.md) → Parse → Validate → Merge to IR → Export → Agent files

Visual flow

What happens:

Load configuration from .aligntrue/config.yaml
Read all *.md files from .aligntrue/rules/
Parse sections from rule files
Validate against JSON Schema
Merge into in-memory IR
Resolve scopes and merge rules
Export to each enabled agent (Cursor, AGENTS.md, etc.)
Write agent files atomically (temp+rename)
Update lockfile (team mode only)

Example:


# Standard sync
aligntrue sync
 
# Preview changes
aligntrue sync --dry-run
 
# Non-interactive (CI)
aligntrue sync --force

Output:


◇ Loading configuration...
◇ Parsing rules...
◇ Syncing to 2 agents...
│
◆ Files written:
│  • .cursor/rules/rule1.mdc
│  • .cursor/rules/rule2.mdc
│  • .cursor/rules/rule3.mdc
│  • AGENTS.md (3 rules)
│
◇ Sync complete! No conflicts detected.

Precedence rules

Rules directory is authoritative

.aligntrue/rules/*.md is the primary source of truth.

Your rules in .aligntrue/rules/ define what IR contains. Agent files are exports.

If you edit both rules and agent files:

aligntrue sync → Rules overwrite agent files (after conflict handling)

Recommended workflow:

Edit .aligntrue/rules/*.md
Run aligntrue sync
All agent files updated automatically

Agent files are read-only

Agent files (Cursor, AGENTS.md, etc.) receive exports from IR and should not be manually edited.

If you edit an agent file:


aligntrue sync
# ⚠ Checksum mismatch: AGENTS.md
#
# This file was manually edited since last sync.
# Backing up to .aligntrue/.backups/files/AGENTS.2025-01-15T10-30-45.md.bak
# Prompt: overwrite / keep / abort (or auto-overwrite if --force/--yes)

Why: Agent files are under AlignTrue’s control. Manual edits are overwritten to maintain consistency.

Best practice: Edit .aligntrue/rules/*.md, not agent files.

Git handling of exports

Exports are generated artifacts. Default git mode for solo/team is ignore, so sync will add agent files to .gitignore. Agents still work because exports exist on disk after aligntrue sync.
Commit exports only for explicit reasons (compliance snapshot, downstream handoff without AlignTrue). Otherwise keep them ignored to avoid merge noise.
Use per-exporter overrides when a specific format must be tracked (for example, git.per_exporter.agents: commit while leaving .cursor/rules ignored).

Manual edit detection

If sync detects manual edits to generated files:


⚠ Checksum mismatch: .cursor/rules/rule1.mdc

This file was manually edited since last sync.

[v] View current content
[o] Overwrite (discard manual edits)
[k] Keep manual edits (skip sync)
[a] Abort sync

Choice:

Checksum tracking:

AlignTrue computes a SHA-256 hash of each generated file per sync
Hashes live in memory during the run to detect manual edits
On mismatch, conflict handling decides whether to overwrite, keep, or abort

Conflict handling:

Interactive (default): prompt with options to view, overwrite, keep, or abort
--yes / --force: overwrite without prompting
--non-interactive without force: aborts on conflict to avoid clobbering edits

Overwriting and backups for agent files

Agent files are overwritten only after conflict handling (prompt or --force/--yes):

Before overwriting: Original content is backed up to .aligntrue/.backups/files/ with a timestamp
During sync: File is overwritten with clean IR content (no merge, no user edits preserved)
Restoring: Use aligntrue backup restore --timestamp <ts> to restore a backup; backups are cleaned up by retention policy (retention_days, minimum_keep)