mirror of
https://bitbucket.org/siakitem/my-pi.git
synced 2026-08-28 08:35:57 +00:00
43 lines
2.6 KiB
Markdown
43 lines
2.6 KiB
Markdown
---
|
||
issue: 118
|
||
issue_title: "refactor: extract gate runner so gates become pure descriptor functions"
|
||
---
|
||
|
||
# Retro: #118 — extract gate runner so gates become pure descriptor functions
|
||
|
||
## Final Retrospective (2026-05-07T03:26:00Z)
|
||
|
||
### Session summary
|
||
|
||
Planned and executed a refactoring that converts all four gate functions (`tool`, `skill-read`, `external-directory`, `bash-external-directory`) from side-effectful functions with 7-field dep interfaces into pure descriptor factories.
|
||
A single `runGateCheck()` runner now handles the check→log→emit→approve cycle, subsuming #112.
|
||
Released as v5.6.0 with zero behavioral change.
|
||
|
||
### Observations
|
||
|
||
#### What went well
|
||
|
||
- **Lift-and-shift migration**: keeping `evaluate*` alongside `describe*` through steps 3–6 meant the full test suite (1216 tests) stayed green at every commit.
|
||
The final removal in step 7 was a clean delete.
|
||
- **`preCheck` field deviation**: the plan didn't anticipate that `describeToolGate` needs `PermissionCheckResult` for message formatting.
|
||
Adding `preCheck` to the descriptor type was a pragmatic deviation that preserved purity without a double `checkPermission` call — worked on first try.
|
||
- **Runner tested once, gates tested purely**: the runner's 16 tests cover all resolution paths; gate tests became simple input→output assertions with zero mocks.
|
||
|
||
#### What caused friction (agent side)
|
||
|
||
- `missing-context` — In step 5, created `runnerDeps` inside the `if (skillDescriptor)` block, then referenced it from the external-directory gate section outside that scope.
|
||
Caused a `ReferenceError` caught by one integration test.
|
||
Impact: one extra edit cycle to hoist the declaration (~30 seconds).
|
||
- `missing-context` — After hoisting shared `runnerDeps` in step 5, forgot the tool gate section (from step 3) already had its own `const runnerDeps`.
|
||
Biome caught the redeclaration.
|
||
Impact: one extra edit to remove the duplicate.
|
||
- `missing-context` — When removing per-gate dep interfaces in step 7, `ToolGateDeps["emitDecision"]` and `ToolGateDeps["checkPermission"]` type annotations remained in `src/handlers/tool-call.ts`.
|
||
Impact: one additional edit to switch to `GateRunnerDeps` references, caught by build.
|
||
- `other` — Autoformat reordered imports in `src/handlers/gates/skill-read.ts` between edits, causing the next `Edit` call's `oldText` to not match.
|
||
Used full file rewrite instead.
|
||
Impact: one extra tool call, no rework.
|
||
|
||
#### What caused friction (user side)
|
||
|
||
- None observed — the user's involvement was limited to plan/TDD/ship commands and one clarifying question about terminology ("descriptor factories"), which was reasonable given the plan's jargon.
|