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**

```bash
echo "git" > .git_path
```

- [ ] **Step 3: Verify the change**

Run: `cat .git_path`

Expected output:
```
git
```

- [ ] **Step 4: Commit**

```bash
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:
```bash
export PATH="/opt/homebrew/bin:/usr/local/bin:$PATH"
```

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

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

# 1. Kill potentially hanging processes
```

- [ ] **Step 2: Fix IP detection (line 41)**

Locate line 41:
```bash
LOCAL_IP=$(ipconfig getifaddr en0 || ipconfig getifaddr en1 || echo "localhost")
```

Replace with:
```bash
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**

```bash
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:
```markdown
### 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**

```bash
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:
```markdown
### 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:
```markdown
### 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**

```bash
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:
```markdown
**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:
```markdown
**Active AI Tools:**
- **Git Binary:** `git` (system PATH, Linux native)
- **Environment:** Use `./backend/venv/` for python tasks.
```

- [ ] **Step 5: Commit**

```bash
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)**

```bash
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