my-pi/pi-permission-system/docs/retro/0110-split-external-directory.md

issue, issue_title

issue	issue_title
110	refactor: split external-directory.ts into focused modules

Retro: #110 — split external-directory into focused modules

Final Retrospective (2026-05-07T16:15:00Z)

Session summary

Split src/external-directory.ts (~760 lines, 4 concerns) into src/node-modules-discovery.ts, src/path-utils.ts (extended from #109), src/handlers/gates/external-directory-messages.ts, and src/handlers/gates/bash-path-extractor.ts. Initially preserved the original file as a barrel re-export; the user's post-ship question exposed the barrel added no value, leading to a follow-up commit that deleted it and colocated gate-specific modules with their consumers. Released as v5.6.3 with zero behavioral change.

Observations

What went well

• Sequencing with #109 paid off. The user asked whether to do #109 or #110 first; recommending #109 first meant path-utils.ts already existed when #110 started, eliminating a path-classification.ts that would have been immediately renamed.
• TDD extraction was clean. 5 steps, all green at every commit. The incremental extract-then-re-export-from-barrel pattern meant no downstream test ever broke during the extraction.
• Post-ship review caught the real abstraction gap. The user's question "is what we really need a higher level abstraction?" took ~10 minutes of import analysis to answer definitively. The follow-up commit was small (12 files, +24/−49 lines) because the extraction was already done — only import paths changed.

What caused friction (agent side)

• premature-convergence — The plan specified "keep external-directory.ts as a barrel re-export" without analyzing whether any consumer actually needed the aggregation. Every consumer used symbols from 1–2 underlying modules; no consumer needed all 20+ symbols together. The barrel was "these things used to be in one file" masquerading as an API boundary. Impact: one extra commit after the issue was closed and shipped, plus re-running CI. User-caught.
• instruction-violation — Wrote #109 at the start of a markdown line in the updated plan, which markdownlint parsed as an ATX H1 heading (same issue as #109 retro). Required a commit retry after the pre-commit hook caught it. Impact: one failed commit attempt, minor. Self-identified via hook output.

What caused friction (user side)

• The user's post-ship question was the most valuable intervention in the session — it transformed a mechanical refactoring into a module-placement decision. Earlier involvement (e.g., during planning) could have avoided the barrel entirely, but the cost was low since the follow-up was small.