feat: vendor permission system source

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

@@ -0,0 +1,45 @@
+---
+issue: 110
+issue_title: "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.