103 lines
3.5 KiB
Markdown
103 lines
3.5 KiB
Markdown
# 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:
|
|
|
|
```bash
|
|
# 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) |