my-pi/pi-permission-system/docs/retro/0055-extract-pure-evaluate.md

issue, issue_title

issue	issue_title
55	Extract pure evaluate() function from PermissionManager

Retro: #55 — Extract pure evaluate() function from PermissionManager

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

Session summary

Extracted Rule, Ruleset, getDefaultAction(), and evaluate() into src/rule.ts, added wildcardMatch() to src/wildcard-matcher.ts, and refactored all five surface branches of PermissionManager.checkPermission() to delegate to evaluate(). Released as v3.6.0 with 23 new tests and zero behavioral change.

Observations

What went well

• Reference equality pattern for synthetic-vs-explicit detection. compiledToRuleset() returns Rule objects that evaluate() returns by reference when matched. ruleset.includes(rule) cleanly distinguishes explicit matches from the synthetic default without modifying the Rule type. This keeps Rule minimal for #56.
• Self-caught semantic drift in skill branch. The initial refactor of the skill branch passed "" as the pattern when skillName was not a string, which would have matched a "*" wildcard skill rule — changing behavior. Caught before committing and preserved the original guard. Impact: no rework, but close to a subtle permission regression.

What caused friction (agent side)

• missing-context — Used Array.prototype.findLast (ES2023) in evaluate() despite the tsconfig targeting ES2022. Not caught until step 13 (npm run build), requiring an extra fix commit (1911f37). The existing codebase already uses manual backwards loops in findCompiledWildcardMatch, which should have been the signal. Impact: one extra commit and a wasted typecheck cycle; no rework to tests or other code. Self-identified at the typecheck step.
• scope-drift — Plan prescribed 6 separate TDD steps (2–7) for getDefaultAction and evaluate() tests, but these naturally formed a single red-green cycle for a pure function with no side effects. Collapsed into one commit without loss. Impact: added friction reading the plan but no rework.

What caused friction (user side)

• No friction observed — the plan was clear and the issue was well-scoped with explicit "what changes" and "what doesn't change" sections.

Changes made

1. Added ES2022 target constraint rule to AGENTS.md § Code Style.