the-nexus/docs/soul-canonical-location.md

SOUL.md Canonical Location Policy

Issue: #1443 - decide: Establish SOUL.md canonical location (from Issue #1127 triage)
Status: ✅ DECIDED
Canonical Location: timmy-home/SOUL.md

Decision

SOUL.md canonical location is timmy-home/SOUL.md.

This decision was made based on:

1. Existing Practice: PR #580 was approved in timmy-home
2. Repository Structure: timmy-home contains core identity files
3. CLAUDE.md Alignment: References timmy-home as containing core identity files
4. Separation of Concerns:
   • timmy-home: Core identity, values, and configuration
   • timmy-config: Operational configuration and tools
   • the-nexus: 3D world and visualization

Current State

SOUL.md in the-nexus

The current SOUL.md in the-nexus is already a reference pointer:

# SOUL.md

> **This file is a reference pointer.** The canonical SOUL.md lives in
> [`timmy-home`](https://forge.alexanderwhitestone.com/Timmy_Foundation/timmy-home/src/branch/main/SOUL.md).
>
> Do not duplicate identity content here. If this repo needs SOUL.md at
> runtime, fetch it from timmy-home or use a submodule reference.

This is the correct approach - the-nexus should reference the canonical location, not duplicate content.

Historical Context

• PR #580 (timmy-home): "Harden SOUL.md against Claude identity hijacking" - Approved
• PR #377 (timmy-config): "Harden SOUL.md against Claude identity hijacking" - Closed as duplicate
• Both PRs had identical diffs, causing confusion

Prevention Measures

1. Documentation

This policy document establishes the canonical location.

2. CODEOWNERS Update

Add SOUL.md to CODEOWNERS to require review for changes:

# SOUL.md requires review from @Timmy
SOUL.md @Timmy
timmy-home/SOUL.md @Timmy

3. PR Template Update

Add reminder to PR template:

## SOUL.md Changes
- [ ] Changes are to `timmy-home/SOUL.md` (canonical location)
- [ ] Not creating duplicate SOUL.md in other repositories
- [ ] Updating reference pointers if needed

4. CI Check (Future)

Add CI check to warn if SOUL.md is modified outside timmy-home.

Implementation

Immediate Actions

1. Verify timmy-home/SOUL.md exists - ✅ Confirmed
2. Verify the-nexus/SOUL.md is reference pointer - ✅ Confirmed
3. Update CODEOWNERS - Add SOUL.md review requirements
4. Document policy - This document

Future Actions

1. Check other repositories - Ensure no duplicate SOUL.md files
2. Update documentation - Reference this policy in CONTRIBUTING.md
3. Monitor for duplicates - Regular checks for SOUL.md in wrong locations

Verification

Check timmy-home/SOUL.md

# Verify canonical location exists
curl -s -H "Authorization: token $TOKEN" \
  "https://forge.alexanderwhitestone.com/api/v1/repos/Timmy_Foundation/timmy-home/contents/SOUL.md"

Check for Duplicates

# Check all repositories for SOUL.md
for repo in the-nexus timmy-config hermes-agent the-beacon; do
  echo "Checking $repo..."
  curl -s -H "Authorization: token $TOKEN" \
    "https://forge.alexanderwhitestone.com/api/v1/repos/Timmy_Foundation/$repo/contents/SOUL.md" \
    | jq -r '.name // "Not found"'
done

Benefits

1. Prevents Duplicate PRs

• No more duplicate SOUL.md changes across repositories
• Clear ownership and review process

2. Clear Ownership

• timmy-home owns SOUL.md
• Changes require review from @Timmy

3. Consistent Identity

• Single source of truth for Timmy's identity
• No divergence between repositories

4. Easier Maintenance

• One place to update SOUL.md
• Clear review and approval process

Related Issues

• Issue #1127: Perplexity Evening Pass triage (identified duplicate SOUL.md)
• Issue #1443: This decision
• PR #580: Approved SOUL.md changes in timmy-home
• PR #377: Closed duplicate SOUL.md changes in timmy-config

Files

• SOUL.md - Reference pointer to timmy-home (this repository)
• timmy-home/SOUL.md - Canonical location
• docs/soul-canonical-location.md - This policy document

Conclusion

SOUL.md canonical location is established as timmy-home/SOUL.md.

This decision:

• ✅ Prevents future duplicate PRs
• ✅ Establishes clear ownership
• ✅ Maintains consistent identity
• ✅ Aligns with existing practice

This issue can be closed.

License

Part of the Timmy Foundation project.