[roadhero]

Phase 1 of the v0.6.0 upstream-separation migration (epic #155). Closes #165 (sub-issue of phase tracker #164).

What this does

Introduces packages/fox-overlay/ — a sibling overlay package that will hold all Fox-in-the-Box-specific code so the forks/hermes-{agent,webui} submodules can pin virgin upstream tags (Phase 8). Phase 1 ships only the scaffold; subsequent phases (2-10) populate it.

packages/fox-overlay/
├── pyproject.toml          # entry-point commented until Phase 3
├── MANIFEST.toml           # empty inventory (Phases 2-7 fill)
├── README.md
├── .fox-removals           # empty manifest with consumer-convention header
├── .gitignore              # *.egg-info/
├── fox_overlay/
│   ├── bootstrap.py        # FOX_OVERLAY_AUTOINSTALL-gated install()
│   ├── webui_modules/      # Phase 5 target
│   ├── webui_patches/      # Phase 6 target
│   └── agent_plugins/      # Phase 3 target
├── webui_static/.gitkeep   # Phase 2 target
├── patches/{webui,agent}/series  # Phase 4 target
├── scripts/check-overlay-basis.sh  # bash stub; Phase 8 makes real
└── tests/test_bootstrap.py # 3 idempotency / autoinstall regression tests

Plus a one-line AGENTS.md Repository-Layout addition and a pnpm-workspace.yaml narrowing.

No behavior change — Dockerfile is untouched, the overlay isn't pip installed in the image yet, no entry-points wired, no patches populated. The container builds bit-identically to today.

Validation gates (per plan §Phase 1)

• ✅ pip install -e packages/fox-overlay/ from a fresh venv: clean editable wheel
• ✅ python -c "import fox_overlay.bootstrap": prints [fox-overlay] bootstrap installed (no-op skeleton)
• ✅ FOX_OVERLAY_AUTOINSTALL=0 opt-out: leaves _INSTALLED=False until manual install() call
• ✅ Container smoke A1-A4 against :8788 (existing v0.5.4 baseline image): all green
• ✅ git diff main...HEAD: only adds files under packages/fox-overlay/ plus 1-line AGENTS.md + 5-line pnpm-workspace.yaml narrowing
• ✅ pytest: 3/3 pass
• ✅ pnpm install --frozen-lockfile: clean

5-hat process

Hat	Result
Architect	6-line brief approved by Dennis 2026-05-16
Engineer (orchestrating Claude)	4 commits on this branch
Reviewer #1 — Senior Backend Engineer	APPROVE; 1 MEDIUM, 2 LOW
Reviewer #2 — DevOps	APPROVE-WITH-CHANGES; 1 BLOCKER-ish (auto-install)
Reviewer #3 — Adversarial	APPROVE-WITH-CHANGES; 2 HIGH, 2 MEDIUM, 4 LOW
QA	PASS — 4/4 validation gates clean

Reviewer findings — ALL actioned (per Dennis "don't leave anything behind" 2026-05-16)

Finding	Severity	Resolution	Where
bootstrap.install() auto-fires at import — load-bearing footgun for Phase 4-6 (DevOps + Adversarial)	HIGH × 2	FOX_OVERLAY_AUTOINSTALL env gate (default on; set =0 to opt out) + module docstring warning	C1
Anti-regression Rule 4 (feature flags) — auto-install ungated	HIGH	Same env gate satisfies Rule 4	C1
pnpm-workspace.yaml globs packages/* (Backend + Adversarial)	MEDIUM × 2	Narrowed to packages/electron explicitly	C3
Anti-regression Rule 3 — no tests added	FAIL	tests/test_bootstrap.py with 3 cases	C4
pyproject.toml [tool.setuptools.packages.find] missing where (Backend)	LOW	Added where = ["."]	C1
check-overlay-basis.sh shebang /bin/sh (Adversarial)	LOW	Switched to /bin/bash for Phase 8 future bash features	C1
.fox-removals comment-safety — risk of # lines being treated as filenames (Adversarial)	LOW	Added consumer-convention header documenting required grep -v '^\s*$|^\s*#' strip pattern	C1
AGENTS.md "phases 2-7" (Adversarial)	LOW	"phases 2-10" — plan goes through Phase 10	C2
Squash commits 1+2 to clean up egg-info history (Adversarial)	MEDIUM	Branch rebuilt as 4 clean commits via soft-reset; force-pushed; egg-info trace eliminated entirely	(history)

Zero open reviewer comments. All 9 findings either resolved in code or rebuilt out of history.

Out of scope (deferred to subsequent phases)

• Dockerfile edits (Phases 2, 3, 8)
• Entry-point activation (Phase 3)
• pip install -e of overlay in the image (Phase 3)
• Patches/series content (Phase 4)
• Submodule re-point (Phase 8)
• CHANGELOG.md ## [0.6.0] entry (Phase 10)

Authorship invariant

All 4 commits authored by roadhero per the migration policy. No Co-authored-by or Generated with Claude Code lines.

---

Closes #165 (Phase 1 sub-issue under #164).