my-pi/pi-permission-system/docs/retro/0317-remove-permission-forwarding-deps.md

issue, issue_title

issue	issue_title
317	Remove PermissionForwardingDeps; inline polling logic as forwarder methods

Retro: #317 — Remove PermissionForwardingDeps; inline polling logic as forwarder methods

Stage: Planning (2026-06-02T00:00:00Z)

Session summary

Produced the implementation plan for the final step (3 of 3) of the forwarding lift-and-shift: inline the polling.ts free functions (confirmPermission, waitForForwardedPermissionApproval, processForwardedPermissionRequests) as private PermissionForwarder methods reading this, dissolve the PermissionForwardingDeps bag into constructor-injected fields, and delete polling.ts. Verified prerequisites [#315] and [#316] are already landed, audited every consumer of the removed symbols, and identified the doc/skill references that name them.

Observations

• Decisive design call: dissolve the bag into individual private readonly fields rather than keeping this.deps, driven by the architecture doc's Step 2 note ("a later step … removes the bag"). The lower-churn this.deps.<field> alternative was considered and rejected.
• The constructor gains a new PermissionForwarderDeps interface (same shape as the deleted PermissionForwardingDeps) consumed at exactly one site (index.ts); the index.ts object literal is unchanged, only its type annotation.
• Type coupling forces a single refactor: commit: deleting polling.ts breaks index.ts, permission-forwarder.test.ts, permission-forwarding.test.ts, and a stale vi.mock in runtime.test.ts simultaneously. That stale mock in runtime.test.ts is provably unused (runtime.ts has no polling import) but must be removed in the same commit to keep module resolution valid.
• getSessionId and formatForwardedPermissionPrompt are exported from polling.ts but have no external consumers — they become module-private functions in the forwarder (verify with pnpm fallow dead-code).
• Three doc surfaces reference removed symbols and need updating in a follow-up docs: commit: architecture.md (mark Phase 3 Step 4 done), permission-prompter.md (stale PermissionForwardingDeps sentence), and .pi/skills/package-pi-permission-system/SKILL.md (the confirmPermission testing note).
• The decomposition (buildForwardedRequest, pollForForwardedResponse, processSingleForwardedRequest) clears the code-design bar — the first two return values, the third owns a cohesive per-request workflow reading this — so it is genuine design, not procedure-splitting.
• Behavior-preservation safety net: composition-root.test.ts "subagent registry sharing" round-trip plus the migrated forwarder behavior tests; this is a refactor: cycle (keep green), not red→green.

Stage: Implementation — TDD (2026-06-02T16:31:00Z)

Session summary

Completed the single refactor commit in one TDD cycle: rewrote permission-forwarder.ts to own the forwarding behavior as private methods, deleted polling.ts, updated index.ts type annotation, rewrote permission-forwarder.test.ts with 5 real behavior tests, pruned 5 stale tests from permission-forwarding.test.ts, removed the dead vi.mock from runtime.test.ts, and committed the follow-up docs: commit updating architecture.md, permission-prompter.md, and SKILL.md. Test count: 1756 → 1753 (removed 8 delegation/free-function tests, added 5 behavior tests). Pre-completion reviewer returned PASS.

Observations

• The plan's currentSessionId parameter on processSingleForwardedRequest was not in the plan's sketch (which showed 4 params) but was added to avoid calling getSessionId(ctx) twice per request loop; clean and correct.
• A trailing blank line introduced by the Python-based block deletion caused a Biome format failure; fixed with pnpm exec biome check --write.
• The getContextSystemPrompt helper passes null as logger to logPermissionForwardingWarning, swallowing the warning silently — the reviewer noted this as a deliberate trade-off documented in an inline comment, not a smell.
• Pre-completion reviewer verdict: PASS. No WARN findings.

Stage: Final Retrospective (2026-06-02T17:00:00Z)

Session summary

One continuous session carried issue #317 from planning through TDD, shipping, and this retrospective. The refactor: landed in a single commit (80028585) plus a docs: follow-up (f03be193), CI passed, and the ship stage closed the entire stacked sequence (#314–#317). The session ran end-to-end without user correction.

Observations

What went well

• Plan→execution fidelity: the plan predicted the exact type-coupling breakage set (index.ts, permission-forwarder.test.ts, permission-forwarding.test.ts, and the stale runtime.test.ts mock) and folded them into one refactor: commit; TDD reproduced it with zero rework and a clean pre-completion PASS.
• The planning symbol-usage audit (grepping getSessionId and formatForwardedPermissionPrompt) correctly predicted they would become module-private with no fallow dead-code fallout — confirmed green at ship.
• Ship cleanly closed the full stacked sequence #314–#317 with tailored per-issue comments, and correctly reasoned that no release-please PR would appear because every commit since pi-permission-system-v10.0.0 is refactor:/docs:.

What caused friction (agent side)

• other (self-identified) — when removing the two migrated describe blocks from permission-forwarding.test.ts, I first renamed them to placeholder names (_placeholder_to_be_removed, _confirmPermission_placeholder) before realizing they needed wholesale deletion, then cut from a marker to EOF with a Python script. Impact: ~2 wasted tool calls (the rename Edit); no rework to the final file.
• other (self-identified) — the Python marker-to-EOF cut left a trailing blank line that failed Biome formatting; fixed with pnpm exec biome check --write. Impact: one extra fix step, caught by the lint gate before commit; no rework.

What caused friction (user side)

• None — the workflow prompts and the pre-completion reviewer carried verification end-to-end with no user intervention needed.

Process observation (not a friction point)

• Issues #314, #315, #316 were still open when #317 shipped, so this ship session closed all four at once. The mechanism is already in the ship-issue prompt (step 5 closes stacked issues because release-please omits refactor: from the changelog), and it worked as designed. Worth confirming whether the earlier ship sessions left their own target issues open intentionally (batched closure for the lift-and-shift sequence) or by omission.

Changes made

1. Appended this Final Retrospective stage entry to packages/pi-permission-system/docs/retro/0317-remove-permission-forwarding-deps.md.
2. No AGENTS.md or prompt changes — the user confirmed retro-only; the two minor friction points were self-corrected by existing verification gates and do not generalize into rules.