tfm_ainventory/docs/superpowers/plans/2026-04-18-macos-to-linux-migration.md

macOS → Linux Ubuntu Migration Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Remove all macOS-specific code and paths, replacing them with Linux-native equivalents for Ubuntu development.

Architecture: Straightforward configuration updates across 6 files. No code logic changes — only platform-specific command/path replacements and documentation updates. Changes are isolated and independent.

Tech Stack: Bash shell scripts, Python (git path resolution), plain text documentation.

---

Task 1: Update .git_path for Linux

Files:

• Modify: .git_path

• Step 1: Read current .git_path

Run: cat .git_path

Expected output:

/Library/Developer/CommandLineTools/usr/bin/git

• Step 2: Replace with Linux standard git path

echo "git" > .git_path

• Step 3: Verify the change

Run: cat .git_path

Expected output:

git

• Step 4: Commit

git add .git_path
git commit -m "chore: update git path for Linux (use system git)"

---

Task 2: Fix IP Detection in start_server.sh

Files:

• Modify: start_server.sh:19,41

• Step 1: Remove Homebrew PATH (line 19)

Read the file and locate line 19:

export PATH="/opt/homebrew/bin:/usr/local/bin:$PATH"

Delete this entire line. New file context (lines 17-22):

fi

echo "🚀 Starting TFM aInventory Stack with Dual Proxy..."

# 1. Kill potentially hanging processes

• Step 2: Fix IP detection (line 41)

Locate line 41:

LOCAL_IP=$(ipconfig getifaddr en0 || ipconfig getifaddr en1 || echo "localhost")

Replace with:

LOCAL_IP=$(hostname -I | awk '{print $1}')

• Step 3: Verify the updated lines

Run: sed -n '17,22p; 39,43p' start_server.sh

Expected output shows:

• Lines 17-22: No export PATH line

• Lines 39-43: hostname -I | awk '{print $1}' instead of ipconfig

• Step 4: Test the IP detection locally

Run: bash -c "LOCAL_IP=\$(hostname -I | awk '{print \$1}'); echo \"Detected IP: \$LOCAL_IP\""

Expected: Outputs your Ubuntu system's primary IP address (e.g., 192.168.x.x, 10.x.x.x, or 127.0.0.1)

• Step 5: Commit

git add start_server.sh
git commit -m "chore: replace macOS commands with Linux equivalents in start_server.sh

- Remove /opt/homebrew/bin PATH injection (macOS Homebrew specific)
- Replace ipconfig with hostname -I for IP detection (Linux native)"

---

Task 3: Update AI_RULES.md — Remove macOS Git Infrastructure Section

Files:

• Modify: AI_RULES.md:106-109

• Step 1: Locate Section 7.5

Run: grep -n "Git Infrastructure Hardening" AI_RULES.md

Expected: Line number showing where Section 7.5 starts (should be around line 106)

• Step 2: Read the section to verify content

Run: sed -n '106,109p' AI_RULES.md

Expected output shows the 4-line macOS git hardening section:

### 7.5 Git Infrastructure Hardening (v1.7.0)
To ensure deployment stability on macOS environments with potentially broken developer tool links (`xcode-select` errors):
- **Direct Binary Mapping:** The system bypasses path resolution by using a hardcoded direct link to the Git binary in `.git_path` (`/Library/Developer/CommandLineTools/usr/bin/git`).
- **Persistence Mandate:** This path is protected by mandatory AI rules and must never be removed or modified to ensure `save-version` and automated deployment scripts remain functional.

• Step 3: Delete Section 7.5

Using Edit tool, remove lines 106-109 entirely. The file should now go from Section 7.4 directly to the end (EOF).

• Step 4: Verify deletion

Run: tail -20 AI_RULES.md

Expected: File ends with Section 7.4 or earlier section (no Section 7.5 visible)

• Step 5: Commit

git add AI_RULES.md
git commit -m "chore: remove macOS-specific Git Infrastructure Hardening section

Section 7.5 no longer applies to Linux environment where git is available in system PATH."

---

Task 4: Update PROJECT_ARCHITECTURE.md — Rewrite Section 7.5

Files:

• Modify: PROJECT_ARCHITECTURE.md:106-109

• Step 1: Locate Section 7.5

Run: grep -n "Git Infrastructure Hardening" PROJECT_ARCHITECTURE.md

Expected: Line number showing Section 7.5 start (should be around line 106)

• Step 2: Read current Section 7.5

Run: sed -n '106,109p' PROJECT_ARCHITECTURE.md

Expected: Same macOS hardening section as in AI_RULES.md

• Step 3: Replace Section 7.5 with Linux-native note

Using Edit tool, replace lines 106-109 with:

### 7.5 Git Infrastructure (Linux Native)

All git operations use the standard `git` command available in system PATH. On Linux systems, this is reliably provided by the git package via the system package manager.

• Step 4: Verify replacement

Run: sed -n '106,109p' PROJECT_ARCHITECTURE.md

Expected output:

### 7.5 Git Infrastructure (Linux Native)

All git operations use the standard `git` command available in system PATH. On Linux systems, this is reliably provided by the git package via the system package manager.

• Step 5: Commit

git add PROJECT_ARCHITECTURE.md
git commit -m "chore: update Git Infrastructure section for Linux environment

Replaced macOS-specific hardening (xcode-select workarounds) with Linux-native approach using system git in PATH."

---

Task 5: Update SESSION_STATE.md — Reflect Linux git binary

Files:

• Modify: SESSION_STATE.md:85

• Step 1: Locate the Git Binary line

Run: grep -n "Git Binary" SESSION_STATE.md

Expected: Line ~85 showing the git binary reference

• Step 2: Read the current line

Run: sed -n '84,86p' SESSION_STATE.md

Expected output:

**Active AI Tools:**
- **Git Binary:** `/Library/Developer/CommandLineTools/usr/bin/git`
- **Environment:** Use `./backend/venv/` for python tasks.

• Step 3: Replace git binary line

Using Edit tool, replace:

- **Git Binary:** `/Library/Developer/CommandLineTools/usr/bin/git`

With:

- **Git Binary:** `git` (system PATH, Linux native)

• Step 4: Verify the change

Run: sed -n '84,86p' SESSION_STATE.md

Expected output:

**Active AI Tools:**
- **Git Binary:** `git` (system PATH, Linux native)
- **Environment:** Use `./backend/venv/` for python tasks.

• Step 5: Commit

git add SESSION_STATE.md
git commit -m "chore: update handover note to reflect Linux git binary"

---

Task 6: Integration Test — Verify All Changes

Files:

• Test: All modified files + functional verification

• Step 1: Verify all files committed

Run: git status

Expected: Clean working directory (no uncommitted changes)

• Step 2: Verify .git_path is correct

Run: cat .git_path

Expected: git (single line, no path)

• Step 3: Verify git operations work

Run: git log --oneline | head -5

Expected: Shows recent commits without errors (proves git in PATH works)

• Step 4: Test save_version.py reads git path

Run: python3 scripts/save_version.py --help 2>&1 || echo "Script executed or errored as expected"

Expected: Script runs or shows usage (proves git path resolution works; won't actually save version without full context)

• Step 5: Verify IP detection logic

Run: bash -c "LOCAL_IP=\$(hostname -I | awk '{print \$1}'); echo \"Primary IP detected: \$LOCAL_IP\""

Expected: Outputs Ubuntu system's primary IP address

• Step 6: Verify documentation is accurate

Run: grep -c "macOS\|ipconfig\|homebrew\|xcode" AI_RULES.md PROJECT_ARCHITECTURE.md SESSION_STATE.md || echo "No macOS references found"

Expected: Exit code 0 or message "No macOS references found" (no macOS-specific references remain in these docs)

• Step 7: View final commit log

Run: git log --oneline | head -6

Expected: Shows 5 migration commits:

1. chore: update handover note to reflect Linux git binary
2. chore: remove macOS-specific Git Infrastructure Hardening section
3. chore: update Git Infrastructure section for Linux environment
4. chore: replace macOS commands with Linux equivalents in start_server.sh
5. chore: update git path for Linux (use system git)

• Step 8: Final commit (integration verification)

git add -A
git commit -m "chore: macOS to Linux migration complete

All platform-specific paths and commands replaced with Linux equivalents:
- .git_path: Use system git instead of /Library/Developer/CommandLineTools
- start_server.sh: Use hostname -I instead of ipconfig
- AI_RULES.md, PROJECT_ARCHITECTURE.md: Remove macOS git hardening docs
- SESSION_STATE.md: Update git binary reference to Linux native

Ready for Ubuntu development, Docker testing, and standalone deployment."

---

Summary

Task	Files	Changes
1	.git_path	Replace path with git
2	start_server.sh	Remove Homebrew PATH, fix IP detection
3	AI_RULES.md	Delete Section 7.5
4	PROJECT_ARCHITECTURE.md	Rewrite Section 7.5
5	SESSION_STATE.md	Update git binary note
6	All	Integration testing + final commit

Total commits: 6 (including final integration verification)
Estimated time: 15-20 minutes