my-pi/pi-permission-system/docs/retro/0532-split-value-guards-by-cohesion.md

---
issue: 532
issue_title: "pi-permission-system: split value-guards.ts by cohesion"
---

# Retro: #532 — pi-permission-system: split value-guards.ts by cohesion

## Stage: Planning (2026-07-07T00:00:00Z)

### Session summary

Planned Phase 8 Step 8: split `value-guards.ts` by cohesion, keeping the generic parsing guards (`toRecord`, `getNonEmptyString`) and moving the domain guards (`isPermissionState`, `isDenyWithReason`) to `types.ts` beside the `PermissionState` / `DenyWithReason` types they narrow.
The plan is a single atomic `refactor:` step (extraction + three `src/` consumer repoints + test move) plus a doc-update step, releasing independently.

### Observations

- The issue's "Proposed change" lists `normalizeOptionalStringArray` and `normalizeOptionalPositiveInt` among the generic guards to keep, but [#547] already removed both (commit `146844aa`) when zod took over config validation.
  The surviving generic set is only `toRecord` + `getNonEmptyString`; `value-guards.ts` is now 38 LOC, not the 56 the issue cites.
  The roadmap step note already records this shrink.
- Domain-guard consumers are exactly three `src/` files (`permission-manager.ts`, `normalize.ts`, `config-loader.ts`) plus `test/value-guards.test.ts`.
  All three already import types from `./types`, so the repoint merges into an existing import source.
- The `no-restricted-imports` ESLint rule on `permission-manager.ts` blocks only `access-intent/access-path`, so importing a guard from `./types` is allowed.
- Removing the two exports from `value-guards.ts` breaks every importer at the type level in the same commit, so extraction + consumer updates + test moves are one atomic step — mirrors [#479]'s single-step `common.ts` split.
- `types.ts` transitions from types-only to types-plus-guards; judged a natural co-location (a guard is the runtime companion of its type) and endorsed by the roadmap, so no `ask_user` gate was needed.
- Doc updates confined to the live `architecture.md` (module-tree lines, Step 8 ✅ marker + Mermaid node, fallow health row 1 → 0); all other doc hits are historical records (`docs/plans`, `docs/retro`, `docs/decisions`, `history/`) that must not be edited.
- Risk flagged: if `fallow` does not clear `value-guards.ts` to 0 targets (its fan-in is on the retained generic guards), record the actual count rather than forcing the health-row edit — the mixed-cohesion smell, not fan-in, is what this step targets.

## Stage: Implementation — TDD (2026-07-07T18:59:00Z)

### Session summary

Executed the plan's single TDD cycle: moved `isPermissionState` and `isDenyWithReason` from `src/value-guards.ts` to `src/types.ts`, repointed the three domain-guard consumers (`permission-manager.ts`, `normalize.ts`, `config-loader.ts`), and split the guard tests into a new `test/types.test.ts`.
Followed with a `docs:` commit marking Phase 8 Step 8 (and the phase itself) complete in `architecture.md`.
All 2272 `pi-permission-system` tests pass (no count delta — assertions moved, none added or removed); full monorepo `check`/`lint`/`test`/`fallow dead-code` all green.

### Observations

- Confirmed the plan's anticipated deviation: `fallow` (the refactoring-target report, not the `dead-code` gate) still flags `src/value-guards.ts` as a target (19 dependents) after the move, because the fan-in comes from the retained generic guards (`toRecord`, `getNonEmptyString`), not the relocated domain guards.
  Per the plan's own Risks section, did not force the health-metric row to the projected 0 — recorded the actual state with an inline explanation instead.
  `pnpm fallow dead-code`, the actual CI gate, stayed clean throughout.
- The autoformatter (`pi-autoformat`) kept the two `./types` imports (guard + type) as separate lines rather than merging them in `normalize.ts` / `config-loader.ts`; both forms resolve identically, so no follow-up needed.
- Added `(complete)` to the Phase 8 heading, matching the convention already used for Phase 7 — all 8 roadmap steps are now ✅.
- A `[#532]` reference inside the module-tree fenced code block had to be corrected to bare `#532` per the markdown-conventions skill (issue refs inside fenced code blocks are bare, matching the block's existing `(#547)` style) — caught before commit.
- Cross-checked the plan's Module-Level Changes file list against `git diff --name-only 7e00da1c^..72cb13a7`: exact match, no drift.
- Unrelated concurrent work from other sessions (issues #530, #531, #554) landed on `main` between the planning and TDD sessions; scoped the pre-completion reviewer's diff explicitly to this issue's two commits to avoid it reviewing unrelated changes.
- Pre-completion reviewer: **PASS**.
  No blocking or non-blocking findings; the fallow health-row deviation was explicitly called out as documented, not a defect.

## Stage: Final Retrospective (2026-07-07T19:15:00Z)

### Session summary

Shipped Phase 8 Step 8 across three clean stages (Planning, TDD, Ship): moved the domain guards `isPermissionState`/`isDenyWithReason` from `value-guards.ts` to `types.ts`, repointed three consumers, split the guard tests into `test/types.test.ts`, and marked Phase 8 complete in `architecture.md`.
CI landed green on `554479f9`, issue #532 was closed, and — as expected for an all-`refactor:`/excluded-`docs:` range — no release was cut; the work auto-batches into the next release.

### Observations

#### What went well

- **The plan pre-priced its own deviation.**
  The plan's Risks section predicted that `fallow` might not clear `value-guards.ts` to 0 targets (the fan-in lives on the retained generic guards, not the moved domain guards) and pre-authorized recording the actual count instead of forcing the projected `0`.
  When the deviation materialized exactly as predicted, the TDD stage applied the pre-agreed handling with no scramble and no re-decision — a case of planning-stage foresight eliminating implementation-stage friction.
  The pre-completion reviewer then classified it as documented, not a defect.
- **Single-atomic-step discipline held.**
  Removing the two exports breaks every importer at the type level in one commit, so the plan folded extraction + three consumer repoints + test move into one step (mirroring [#479]).
  Execution matched: one `refactor:` commit, `pnpm run check` run immediately after the import change, clean.
- **Incremental verification throughout.**
  Red ran the affected test file, Green re-ran it, `pnpm run check` fired right after the shared-import change, then full suite → lint → `fallow dead-code` — no end-of-session verification pile-up.

#### What caused friction (agent side)

- `other` (tool-interaction) — the first Red-phase `Edit` batch was rejected with `edits.1.newText: must have required properties newText` when a block-deletion used an empty-string `newText`; the immediate retry with the same empty-string replacement succeeded.
  Impact: one extra tool call, no rework, no behavior effect.
  Too minor and too generic (not project-specific) to warrant a rule.
- `other` (convention nuance, self-identified) — a `[#532]` reference-style link was initially placed inside the `architecture.md` module-tree fenced code block; caught against the `markdown-conventions` rule (issue refs inside fenced blocks are bare, matching the block's `(#547)` style) and corrected to bare `#532` before commit.
  Impact: caught pre-commit, no rework.

#### What caused friction (user side)

- None.
  The issue was operator-authored, the plan was unambiguous, and no mid-session correction was needed.

### Changes made

1. Appended this Final Retrospective stage entry to `packages/pi-permission-system/docs/retro/0532-split-value-guards-by-cohesion.md`.
   No `AGENTS.md` or prompt changes — the session surfaced no reusable process gap.

[#479]: https://github.com/gotgenes/pi-packages/issues/479
[#547]: https://github.com/gotgenes/pi-packages/issues/547