my-pi/pi-permission-system/docs/retro/0053-home-directory-expansion.md

issue, issue_title

issue	issue_title
53	Support ~/$HOME expansion in permission config patterns

Retro: #53 — Support ~/$HOME expansion in permission config patterns

Final Retrospective (2026-05-05T03:09:00Z)

Session summary

Implemented ~/ and $HOME/ prefix expansion in wildcard permission patterns, shipping as v4.8.0. The change adds a single utility (src/expand-home.ts) integrated into compileWildcardPattern(), making configs portable across machines. Completed in 4 functional commits + 1 docs commit with zero regressions across 944 tests.

Observations

What went well

• Integration point was surgically minimal — one import + one line in compileWildcardPattern() with zero changes to callers.
• The plan's prediction that step 6 ("no code change expected") would pass immediately was correct — the integration tests were green without additional work.
• Using the real homedir() in the integration test (permission-manager-unified.test.ts) avoided a complex vi.mock setup that would have risked breaking the file's tmpdir() dependency.

What caused friction (agent side)

• instruction-violation — First draft of tests/expand-home.test.ts used await import("node:os") inside a non-async function. AGENTS.md explicitly documents the vi.hoisted() + vi.mock() pattern, and tests/bash-external-directory.test.ts demonstrates the correct approach 4 lines in. Self-identified after autoformat/vitest failure. Impact: one file rewrite (< 30 seconds of rework, no wasted commits).

What caused friction (user side)

• None observed. The issue spec was detailed and unambiguous, including prior art and exact scope.