my-pi/pi-permission-system/docs/retro/0126-extract-extension-paths.md

issue, issue_title

issue	issue_title
126	refactor: extract ExtensionPaths value object from ExtensionRuntime

Retro: #126 — extract ExtensionPaths value object

Final Retrospective (2026-05-08T00:20:00Z)

Session summary

Extracted six immutable path fields from ExtensionRuntime into a new ExtensionPaths interface and computeExtensionPaths() factory in src/extension-paths.ts. Updated ExtensionRuntime to extends ExtensionPaths, delegated path computation in createExtensionRuntime, and narrowed HandlerDeps.piInfrastructureDirs to readonly string[]. Shipped as v5.7.0 with zero behavioral change. 11 new unit tests; total suite 1245 tests across 55 files.

Observations

What went well

• Plan-to-ship pipeline was smooth. Three phases (plan → TDD → ship) completed in a single session with no rework. The plan's risk table predicted the exact readonly string[] assignability issue and the discoverGlobalNodeModulesRoot mock-interception strategy, both of which played out as described.
• Transitive mock interception worked cleanly. The existing vi.mock("../src/node-modules-discovery") in runtime.test.ts continued to intercept correctly through computeExtensionPaths, avoiding any mock-target migration. The plan listed this as the simpler of two options and it proved correct.

What caused friction (agent side)

• missing-context — The plan's Module-Level Changes section listed src/handlers/types.ts as "Unchanged" but the readonly string[] narrowing of piInfrastructureDirs in ExtensionPaths made HandlerDeps.piInfrastructureDirs: string[] incompatible at the assignment site in src/index.ts. Caught by pnpm run build during cycle 2. Impact: one extra edit to src/handlers/types.ts folded into the refactor commit — no rework, added ~30 seconds. Self-identified via compiler output.

What caused friction (user side)

• None observed.