my-pi/pi-permission-system/docs/retro/0006-log-resolved-config-paths.md

issue, issue_title

issue	issue_title
6	Log resolved config paths at startup so misconfiguration is debuggable

Retro: #6 — Log resolved config paths at startup so misconfiguration is debuggable

Final Retrospective (2026-05-02T17:15:00Z)

Session summary

Planned, implemented, and shipped issue #6 across three prompt templates (/plan-issue, /tdd-plan, /ship-issue). The feature adds a config.resolved review-log entry at every session_start listing all policy and extension config paths with existence flags. Released as v0.6.0 with no breaking changes.

Observations

What went well

• The first /ship-issue invocation correctly detected that only a plan commit existed and refused to close the issue — conservative behavior matching the project's least-privilege philosophy.
• TDD execution was clean: 5 commits in logical order, all tests green on first pass after implementation.
• Extracting src/config-reporter.ts as a standalone module (plan left this as an open question) kept the change small and testable.

What caused friction (agent side)

• missing-context — .gitignore included docs/ (upstream excluded generated docs), so git add docs/plans/ failed during the plan phase, requiring git add -f. Self-identified. Impact: one extra tool call and retry; root-caused during retro — upstream's ignore was speculative (no doc generation tooling exists), so docs/ was removed from .gitignore entirely.

• wrong-abstraction — Used as unknown as Record<string, unknown> double-cast in logResolvedConfigPaths() to pass a typed ResolvedConfigLogEntry to writeReviewLog() which accepts Record<string, unknown>. This works but bypasses type safety. Impact: no rework, but leaves a type smell in src/index.ts (lines 1558, 1562).

• missing-context — Did not notice until post-implementation that src/index.ts has two duplicate session_start handlers (lines 1566, 1584) performing identical setup. Added logResolvedConfigPaths() to both, which means the config.resolved entry is emitted twice per session start. Impact: duplicate log entries; latent bug amplified but not introduced by this change.

What caused friction (user side)

• No user-side friction observed. The three-template workflow (/plan-issue → /tdd-plan → /ship-issue) ran without manual corrections.

Changes made

1. .gitignore — Removed the docs/ entry entirely (upstream added it speculatively for "generated documentation" but no doc generation tooling exists).
2. AGENTS.md — Added "Runtime Caveats" section noting the duplicate session_start handlers that must be kept in sync.
3. docs/retro/0006-log-resolved-config-paths.md — This file.