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

SOUL.md Canonical Location Policy

Issue: #1127 - Perplexity Evening Pass triage identified duplicate SOUL.md files causing duplicate PRs.

Current State

As of 2026-04-14:

• SOUL.md exists in timmy-home (canonical location)
• SOUL.md was also in timmy-config (causing duplicate PR #377)

Problem

The triage found:

• PR #580 in timmy-home: "Harden SOUL.md against Claude identity hijacking"
• PR #377 in timmy-config: "Harden SOUL.md against Claude identity hijacking" (exact same diff)

This created confusion and wasted review effort on duplicate work.

Canonical Location Decision

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

Rationale

1. Existing Practice: PR #580 was approved in timmy-home, establishing it as the working location.

2. Repository Structure: timmy-home contains core identity and configuration files:

   • SOUL.md (Timmy's identity and values)
   • CLAUDE.md (Claude configuration)
   • Core documentation and policies

3. CLAUDE.md Alignment: The CLAUDE.md file in the-nexus 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

Implementation

Immediate Actions

1. Remove duplicate SOUL.md from timmy-config (if it still exists)

   • Check if timmy-config/SOUL.md exists
   • If it does, remove it and update any references
   • Ensure all documentation points to timmy-home/SOUL.md

2. Update CODEOWNERS (if needed)

   • Ensure SOUL.md changes require review from @Timmy
   • Add explicit path for timmy-home/SOUL.md

3. Document in CONTRIBUTING.md

   • Add section about canonical file locations
   • Specify that SOUL.md changes should only be made in timmy-home

Prevention Measures

1. Git Hooks or CI Checks

   • Warn if SOUL.md is created outside timmy-home
   • Check for duplicate SOUL.md files across repos

2. Documentation Updates

   • Update all references to point to timmy-home/SOUL.md
   • Ensure onboarding docs mention canonical location

3. Code Review Guidelines

   • Reviewers should check that SOUL.md changes are in timmy-home
   • Reject PRs that modify SOUL.md in other repositories

Verification

To verify canonical location:

# Check if SOUL.md exists in timmy-home
curl -H "Authorization: token $TOKEN" \
  https://forge.alexanderwhitestone.com/api/v1/repos/Timmy_Foundation/timmy-home/contents/SOUL.md

# Check if SOUL.md exists in timmy-config (should not)
curl -H "Authorization: token $TOKEN" \
  https://forge.alexanderwhitestone.com/api/v1/repos/Timmy_Foundation/timmy-config/contents/SOUL.md

Future Considerations

1. Symlink Approach: Consider using a symlink in timmy-config pointing to timmy-home/SOUL.md if both locations are needed for technical reasons.

2. Content Synchronization: If SOUL.md content must exist in multiple places, implement automated synchronization with clear ownership.

3. Version Control: Ensure all changes to SOUL.md go through proper review process in timmy-home.

Conclusion

Establishing timmy-home/SOUL.md as the canonical location:

• ✅ Prevents duplicate PRs like #580/#377
• ✅ Maintains clear ownership and review process
• ✅ Aligns with existing repository structure
• ✅ Reduces confusion and wasted effort

This policy should be documented in CONTRIBUTING.md and enforced through code review guidelines.

Date: 2026-04-14
Status: RECOMMENDED (requires team decision)