E22 — Pykit simplification
| State | Closed |
| Start Date | 2026-11-14 |
| Closed Date | 2026-11-17 |
Simplify the existing ten packages, their tests and documentation. Give shared policy one owner, remove redundant work, and keep framework adapters focused on translation. Correctness defects found during the review get regression cases before refactoring. Performance work starts with measurements and preserves the observable contract unless a separate decision explicitly changes it.
The review and proposed design explains the evidence, priorities, tradeoffs and measurement plan. Features are in Release 9; implementation is limited to its stories, and the epic authorizes no dependency addition, publishing or history rewrite.
Order
- F22.3 establishes behavioral coverage and representative measurements.
- Fix the correctness cases in each affected package before moving its code.
- F22.4 to F22.13 simplify packages independently. Shared HTTP policy in F22.7 and identity policy in F22.8 precede their adapter changes in F22.9/F22.10.
- F22.2 updates consumer documentation with each package change. F22.1 cuts settled spec prose after those changes, preserving unfinished work.
A decision story is settled with the owner before the stories that depend on it.
A build story gets its brief, _briefs/<story>.md, when it is next, so each
brief is written against current code. A contract settled while writing a brief
goes into the story's acceptance, because the brief is deleted when the story
closes.
Scope constraints
- Keep published package boundaries, optional extras and curated facades. A source move within a package must preserve supported imports; a move across packages follows ADR-0002 and has no compatibility alias.
- Keep RFC wire behavior, security controls, denied-path tests, transaction guarantees and standalone package installs. An intentional behavior change needs its own regression test, changelog entry and versioning assessment.
- Do not reopen deferred Azure, codegen, messaging, fixtures, Celery or queue work, or promote parked ideas. E15's deferred extractions stay there.
- Generated tasks, workflows and routing rules remain kiln-owned. Any desired change to their contract is a separate upstream request, not an in-place edit.
- Preserve permanent IDs, closed work and shipped release records. No squash, branch deletion, retagging or replacement of the existing epic inventory.
Completion
Each feature supplies observable acceptance below. Package changes pass the
narrow relevant tests, formatting, typing and import checks through task; the
completed epic passes task validate. The performance comparison names inputs,
environment, time, peak memory and operation counts; it makes no unmeasured
speedup claim. Documentation generation is idempotent and all eleven sites build
strictly through task docs:build.
Considered and rejected
- A package split or a universal adapter framework as the default cleanup. Neither follows from file size or duplicated syntax alone.
- A fixed line-count or percentage reduction target. It rewards relocating complexity and deleting useful contracts; acceptance follows behavior and eliminated duplication instead.
- Rewriting specs into a new taxonomy or squashing repository history. Existing IDs, unfinished features and released packages make this a separate decision.