feat: vendor permission system source

2026-08-28 08:35:57 +00:00 · 2026-08-19 14:35:19 +08:00
parent 198584daf8
commit 410c50a3e5
809 changed files with 157793 additions and 139 deletions
@@ -0,0 +1,42 @@
+---
+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.