my-pi/pi-permission-system/docs/retro/0010-consolidate-config-layout.md

issue, issue_title

issue	issue_title
10	Consolidate config into .pi/extensions/pi-permission-system/config.json (match pi-autoformat convention)

Retro: #10 — Consolidate config layout

Final Retrospective (2026-05-03T03:30:00Z)

Session summary

Implemented the full config consolidation: new config-paths.ts and config-loader.ts modules, rewired permission-manager.ts, index.ts, config-reporter.ts, and all test harnesses to the new extensions/<id>/config.json layout. Legacy-path detection and merge landed with migration warnings. Schema, example, README, and AGENTS.md updated in lockstep. Released as v3.0.0 (breaking change). Post-release, enriched the JSON schema with examples, defaults, markdownDescription, deprecated hints, and per-enum descriptions.

Observations

What went well

• The plan's TDD order was close enough to execute linearly. Steps 7 (logging) and 10 (config-modal) were naturally absorbed into step 9 because the existing code was already parameterized — recognizing this and collapsing them avoided empty commits.
• Legacy-path detection worked correctly on first implementation. The normalize() comparison to avoid false positives when the extension root happens to equal the new global path was tested and caught a real edge case.
• The schema enrichment after shipping was a clean, user-driven iteration. The ask_user interaction surfaced five concrete improvements; the user selected all five and the result is a significantly better editor experience.

What caused friction (agent side)

1. missing-context — In step 9, I cached getAgentDir() as the module-level constant PI_AGENT_DIR and passed it into createPermissionManagerForCwd. Tests set PI_CODING_AGENT_DIR after the module was imported, so PI_AGENT_DIR was stale. This caused 4 test failures in the external-directory tests. Diagnosing the root cause required tracing through piPermissionSystemExtension init → PermissionManager constructor → defaultGlobalConfigPath() → getAgentDir() call timing. Impact: ~3 edit-run-debug cycles and several minutes of investigation. Self-identified — I traced the failure to the stale constant without user intervention.

2. premature-convergence — In step 6, I initially changed defaultGlobalConfigPath() in permission-manager.ts to use the new layout path, which immediately broke 5 integration tests. I had to revert that change and defer it to step 9. A closer reading of the test harness flow before changing the default path would have shown the dependency. Impact: one revert edit, minor rework. Self-identified.

3. missing-context (formatting) — Three commits were rejected by the Biome pre-commit hook. Each required npm run lint:fix and re-staging. pi-autoformat is configured for this project and should have formatted files automatically on agent_end, but the /tdd-plan workflow commits immediately after tests go green — likely before agent_end fires the formatter flush. The friction is not inherent to Write/Edit tools; it is a sequencing gap between the TDD commit cadence and the autoformatter's agent_end trigger. Impact: added friction but no rework.

What caused friction (user side)

• None observed. The user's issue body was exceptionally detailed (proposed file shape, layout question resolved, migration plan, acceptance criteria). This eliminated ambiguity that would normally require ask_user during planning.

Changes made

1. Added rule to AGENTS.md § Code Style: do not cache getAgentDir() at module scope.