Team-managed sections

Team-managed sections let you designate specific sections as controlled by the team lead, while allowing engineers to add their own personal sections.

How it works

Configuration

In .aligntrue/config.yaml:


mode: team
 
managed:
  sections:
    - "Security"
    - "Compliance"
    - "Code Review Standards"
  source_url: "https://github.com/company/rules" # Optional: for display

In exported files

Team-managed sections are marked with [TEAM-MANAGED] prefix and HTML comments:


<!-- [TEAM-MANAGED]: This section is managed by your team.
Local edits will be preserved in backups but may be overwritten on next sync.
To keep changes, rename the section or remove from managed list. -->
 
## Security
 
[Team-controlled content here]

What happens when you edit

You edit a team-managed section locally
Run aligntrue sync
Your changes merge to IR (two-way sync)
Lockfile validation checks bundle hash
- Soft mode: Warning shown, sync continues
- Strict mode: Blocked until approved
On next sync from team source: Your edits may be overwritten
Your edits are preserved in backups

Recovering your changes

If your edits to a team-managed section are overwritten:


# View backups
aligntrue backup list
 
# Restore from backup
aligntrue backup restore --to <timestamp>
 
# Or view backup diff
aligntrue revert --preview

Keeping your changes

To keep your version of a team-managed section:

Option 1: Rename the section


## Security (My Team)
 
[Your version here]

Option 2: Remove from managed list

Ask team lead to remove from managed.sections in config.

Best practices

For team leads

Be selective - Only manage sections that need central control
Document clearly - Use managed.source_url to point to source repo
Review regularly - Check for conflicts between team and personal sections
Communicate changes - Announce when updating managed sections

For team members

Respect markers - Avoid editing [TEAM-MANAGED] sections
Use personal sections - Add your own sections with unique names
Check backups - If you accidentally edit managed sections
Rename if needed - Create personal variants of managed sections

Example workflow

Team lead sets up managed sections


# In central rules repo
cat > .aligntrue/config.yaml << EOF
mode: team
managed:
  sections:
    - "Security"
    - "Compliance"
  source_url: "https://github.com/company/rules"
EOF
 
git add .aligntrue/config.yaml
git commit -m "Define team-managed sections"
git push

Engineer adds personal section


# In engineer's repo (pulls from central)
aligntrue sync # Gets team rules
 
# Edit AGENTS.md - add personal section
echo "## My Testing Preferences" >> AGENTS.md
echo "I prefer Jest with coverage > 80%" >> AGENTS.md
 
aligntrue sync # Syncs personal + team sections

Engineer accidentally edits managed section


# Edit team-managed "Security" section
nano AGENTS.md # Changes "Security" section
 
aligntrue sync
# ⚠ Warning: Edited team-managed section "Security"
# Your changes are backed up and may be overwritten on next team sync
 
# Later, team sync overwrites it
aligntrue sync # Pulls latest from team
 
# Recover your version
aligntrue backup list
aligntrue revert --preview
# Copy your changes if you want to keep them