|
| 1 | +# Spec: v0.2 retrospective and planning/ housekeeping |
| 2 | + |
| 3 | +**Date:** 2026-06-04 |
| 4 | +**Topic slug:** `v0.2-retro-and-housekeeping` |
| 5 | +**Status:** drafted, awaiting user review |
| 6 | + |
| 7 | +## Purpose |
| 8 | + |
| 9 | +Close the books on the v0.2 thin-httpx2-wrapper pivot (shipped 2026-06-04 as PR #20, tag `0.2.0`) before opening the 0.3.0 work cycle. Three deliverables: |
| 10 | + |
| 11 | +1. A written retrospective on the pivot. |
| 12 | +2. Cleanup of `planning/` so `specs/` and `plans/` are empty for the next active feature. |
| 13 | +3. Triage of `planning/deferred-work.md` so it reflects what is actually in scope for 0.3.0. |
| 14 | + |
| 15 | +Auto-memory updates land as part of the same bundle so future sessions start with an accurate model of the repo. |
| 16 | + |
| 17 | +A separate spec — `planning/specs/2026-06-04-pydantic-optional-extra-design.md` — will cover the 0.3.0 feature work (pydantic as an optional extra + payload-edge tests for `PydanticDecoder`). That spec is **out of scope here**; this one only closes out v0.2. |
| 18 | + |
| 19 | +## Non-goals |
| 20 | + |
| 21 | +- No code changes to `src/httpware/`. |
| 22 | +- No version bump, no release. |
| 23 | +- No mkdocs site or CI changes. |
| 24 | +- No resolution of the `_get_adapter` per-instance scoping question (stays open in `deferred-work.md`). |
| 25 | + |
| 26 | +## Deliverable 1 — Retrospective doc |
| 27 | + |
| 28 | +**Path:** `planning/retros/2026-06-04-v0.2-thin-wrapper-pivot.md` |
| 29 | + |
| 30 | +The `planning/retros/` directory is new; this is the first entry. Future retros (release-level, epic-level) land here with the same date-prefixed naming. |
| 31 | + |
| 32 | +**Required sections:** |
| 33 | + |
| 34 | +1. **What shipped (0.1.0 → 0.2.0).** Bullets citing PR #20, key commits (`ce293c1` tear-down, `974d84c` errors, `635de95` middleware, `ab262b4` AsyncClient construction, `1e4a027` version bump), and `pre-v0.2-pivot` tag as the recovery anchor. |
| 35 | +2. **What the pivot bought us.** Concrete wins: surface shrank from 14 files to 8; the `Transport` abstraction is gone; `httpx2.Response` lives inside every `StatusError` (callers get full request/response context for free); `httpx2.MockTransport` replaces the bespoke `RecordedTransport` and cuts a maintenance burden. |
| 36 | +3. **What the pivot cost.** Public 0.x break for any consumer of `httpware.Request`/`Response`/`StreamResponse`/`Limits`/`Timeout`/`ClientConfig`/`Transport`/`Httpx2Transport`/`RecordedTransport`. Six specs in `planning/specs/` went from "ship roadmap" to archive material (Story 1-8 RecordedTransport, 2-3 immutability helpers, 2-4 auth coercion, 4-1 StreamResponse, 4-2 transport stream impl, 5-3 Redactor). The auth-coercion feature shipped in Epic 2 and was removed in the same release cycle. |
| 37 | +4. **Decisions worth keeping.** The three-seam architecture (AsyncClient ↔ Middleware, AsyncClient ↔ ResponseDecoder, httpware ↔ optional extras). Status-keyed exceptions taking a single positional `response: httpx2.Response`. Single-pass decoder protocol (`decode(content: bytes, model: type[T]) -> T`). Optional-extras pattern (one extra per dedicated module). |
| 38 | +5. **Decisions to revisit before 1.0.** Pydantic-required-vs-optional (resolved into 0.3.0 work in a follow-up spec); default-decoder model; periodic `grep -rE 'httpx2\._' src/httpware/` audit on each release. |
| 39 | +6. **Lessons.** Three terse lines: writing `engineering.md` *after* the pivot was the right ordering — it captured the actual design instead of an aspirational one; `deferred-work.md` made the pivot's blast radius obvious because every closed item cited a host file that no longer existed; specs survive their own death — `planning/archive/` keeps the road-not-taken legible. |
| 40 | + |
| 41 | +The doc targets ≈1.5 pages. No code blocks beyond minimal commit citations. |
| 42 | + |
| 43 | +## Deliverable 2 — Planning directory cleanup |
| 44 | + |
| 45 | +### 2.1 New directory structure |
| 46 | + |
| 47 | +``` |
| 48 | +planning/ |
| 49 | +├── engineering.md |
| 50 | +├── deferred-work.md |
| 51 | +├── retros/ |
| 52 | +│ └── 2026-06-04-v0.2-thin-wrapper-pivot.md |
| 53 | +├── releases/ |
| 54 | +│ └── 0.2.0.md |
| 55 | +├── specs/ # empty after this PR |
| 56 | +├── plans/ # empty after this PR |
| 57 | +└── archive/ |
| 58 | + ├── specs/ # 15 files |
| 59 | + └── plans/ # 13 files |
| 60 | +``` |
| 61 | + |
| 62 | +### 2.2 Archive moves (`git mv`, preserves history) |
| 63 | + |
| 64 | +All 15 design specs in `planning/specs/` except `2026-06-03-release-notes-0.2.0.md` get moved to `planning/archive/specs/`: |
| 65 | + |
| 66 | +- `2026-05-31-asyncclient-design.md` |
| 67 | +- `2026-05-31-bmad-to-superpowers-transition-design.md` |
| 68 | +- `2026-05-31-middleware-protocol-and-chain-design.md` |
| 69 | +- `2026-05-31-msgspec-decoder-via-extras-design.md` |
| 70 | +- `2026-05-31-phase-shortcut-decorators-design.md` |
| 71 | +- `2026-05-31-recordedtransport-design.md` |
| 72 | +- `2026-05-31-release-0.1.0-prep-design.md` |
| 73 | +- `2026-05-31-request-immutability-helpers-design.md` |
| 74 | +- `2026-05-31-shipped-work-review.md` |
| 75 | +- `2026-06-01-auth-coercion-design.md` |
| 76 | +- `2026-06-02-docs-reorg-and-mkdocs-design.md` |
| 77 | +- `2026-06-02-project-hygiene-tidy-design.md` |
| 78 | +- `2026-06-03-input-validation-pass-design.md` |
| 79 | +- `2026-06-03-thin-httpx2-wrapper-design.md` |
| 80 | + |
| 81 | +All 13 plans in `planning/plans/` get moved to `planning/archive/plans/`: |
| 82 | + |
| 83 | +- `2026-05-31-asyncclient-plan.md` |
| 84 | +- `2026-05-31-bmad-to-superpowers-transition-plan.md` |
| 85 | +- `2026-05-31-middleware-protocol-and-chain-plan.md` |
| 86 | +- `2026-05-31-msgspec-decoder-via-extras-plan.md` |
| 87 | +- `2026-05-31-phase-shortcut-decorators-plan.md` |
| 88 | +- `2026-05-31-recordedtransport-plan.md` |
| 89 | +- `2026-05-31-release-0.1.0-prep-plan.md` |
| 90 | +- `2026-05-31-request-immutability-helpers-plan.md` |
| 91 | +- `2026-06-01-auth-coercion-plan.md` |
| 92 | +- `2026-06-02-docs-reorg-and-mkdocs-plan.md` |
| 93 | +- `2026-06-02-project-hygiene-tidy-plan.md` |
| 94 | +- `2026-06-03-input-validation-pass-plan.md` |
| 95 | +- `2026-06-03-thin-httpx2-wrapper-plan.md` |
| 96 | + |
| 97 | +### 2.3 Release-notes relocation |
| 98 | + |
| 99 | +`planning/specs/2026-06-03-release-notes-0.2.0.md` is misfiled — it's release-note content, not a design. `git mv` it to `planning/releases/0.2.0.md`. The `planning/releases/` directory is new. Future releases land there as `0.3.0.md`, etc. |
| 100 | + |
| 101 | +### 2.4 This spec stays at top level |
| 102 | + |
| 103 | +The current file (`planning/specs/2026-06-04-v0.2-retro-and-housekeeping-design.md`) remains in `planning/specs/` because it is the active design for this PR. After the housekeeping PR merges, it gets archived along with the next batch of delivered specs. |
| 104 | + |
| 105 | +### 2.5 CLAUDE.md update |
| 106 | + |
| 107 | +Update the "Where to find what" bullet list in `CLAUDE.md` (repo root) to reference `planning/archive/`, `planning/retros/`, and `planning/releases/`: |
| 108 | + |
| 109 | +Bullet content (executor should match the existing markdown-link style — `[`path`](path)` — already used in CLAUDE.md): |
| 110 | + |
| 111 | +- `planning/engineering.md` — canonical design reference. |
| 112 | +- `planning/deferred-work.md` — review-surfaced items not actionable now. |
| 113 | +- `planning/specs/` and `planning/plans/` — per-feature design specs and implementation plans (active work). |
| 114 | +- `planning/archive/{specs,plans}/` — shipped/superseded work, kept for historical context. |
| 115 | +- `planning/retros/` — release- and epic-level retrospectives. |
| 116 | +- `planning/releases/` — per-version release notes (also published on GitHub Releases). |
| 117 | + |
| 118 | +## Deliverable 3 — deferred-work.md triage |
| 119 | + |
| 120 | +### 3.1 Items to delete entirely |
| 121 | + |
| 122 | +These no longer reflect intended direction; remove from `planning/deferred-work.md` rather than keeping them open: |
| 123 | + |
| 124 | +- **"Unpinned `ruff`/`ty` with `select=["ALL"]`"** — current floating-version policy is intentional; CI breakage on new rules will be addressed reactively. |
| 125 | +- **"No `[test]` extra; CI installs all extras"** — the bundled install pattern is intentional; the cost is acceptable. |
| 126 | + |
| 127 | +### 3.2 Items to keep open (unchanged) |
| 128 | + |
| 129 | +- **`_get_adapter` `lru_cache` is module-global, not per-decoder instance** — still genuinely deferred (no configurable `PydanticDecoder` exists yet). |
| 130 | +- **Empty/malformed payload tests** — folded into the 0.3.0 follow-up spec; mark as "in progress for 0.3.0" rather than deleting, so the trail is visible. |
| 131 | + |
| 132 | +### 3.3 Items to update with progress link |
| 133 | + |
| 134 | +- **"`pydantic` import not guarded the way `msgspec` is"** — annotate with "→ resolved in 0.3.0 by `2026-06-04-pydantic-optional-extra-design.md`" (the follow-up spec). Keep the entry until the follow-up PR merges, then move to a "Closed" section. |
| 135 | + |
| 136 | +### 3.4 Resulting deferred-work.md structure |
| 137 | + |
| 138 | +After this PR: |
| 139 | + |
| 140 | +- **Open / Decoder-side:** `_get_adapter` scoping (1 item). |
| 141 | +- **Open / Decoder-side, in progress for 0.3.0:** malformed-payload tests, pydantic optional-extra guard (2 items). |
| 142 | +- **Closed by the v0.2 thin-wrapper pivot (2026-06-03):** unchanged (12 items, already present). |
| 143 | + |
| 144 | +## Deliverable 4 — Auto-memory updates |
| 145 | + |
| 146 | +Path: `/Users/kevinsmith/.claude/projects/-Users-kevinsmith-src-pypi-httpware/memory/`. |
| 147 | + |
| 148 | +### 4.1 Edit existing memories |
| 149 | + |
| 150 | +- **`epic_2_complete.md`** — strike "Next ship target is Epic 3 (resilience middleware) for 0.2.0". Replace with: "0.2.0 shipped as the thin-httpx2-wrapper pivot (PR #20, 2026-06-04). Epic 3 (resilience) is the surviving roadmap target post-pivot but is not the next ship." |
| 151 | +- **`workflow_superpowers_cutover.md`** — replace `docs/superpowers/{specs,plans}/` with `planning/{specs,plans}/`. Note the 2026-06-02 rename (commit `d295fd4`). Add: `planning/archive/` for shipped/superseded work. |
| 152 | + |
| 153 | +### 4.2 Add new memory |
| 154 | + |
| 155 | +- **`release_0_2_0_shipped.md`** — date 2026-06-04, PR #20, thin-httpx2-wrapper pivot. Reference the retro doc. Note: tag `pre-v0.2-pivot` is the recovery anchor for the pre-pivot tree. |
| 156 | + |
| 157 | +### 4.3 Update MEMORY.md index |
| 158 | + |
| 159 | +Add the new memory line, refresh the descriptions for the edited memories. |
| 160 | + |
| 161 | +## Out of scope (handled in the follow-up 0.3.0 spec) |
| 162 | + |
| 163 | +The follow-up spec at `planning/specs/2026-06-04-pydantic-optional-extra-design.md` covers: |
| 164 | + |
| 165 | +- Adding `is_pydantic_installed` to `_internal/import_checker.py`. |
| 166 | +- Guarding the `pydantic` import in `decoders/pydantic.py` like `decoders/msgspec.py`. |
| 167 | +- Removing the unconditional `from httpware.decoders.pydantic import PydanticDecoder` from `client.py`. |
| 168 | +- Lazy default-decoder construction with fail-fast at `AsyncClient.__init__` when `decoder is None` and pydantic is not installed. |
| 169 | +- Moving `pydantic` from `[project] dependencies` to `[project.optional-dependencies]`. |
| 170 | +- Adding `pydantic` to the `all` extra. |
| 171 | +- Updating `README.md` install instructions. |
| 172 | +- Updating `planning/engineering.md` §1 and §7. |
| 173 | +- Adding empty/malformed payload tests for `PydanticDecoder`. |
| 174 | + |
| 175 | +This is breaking and ships as 0.3.0. |
| 176 | + |
| 177 | +## Execution order |
| 178 | + |
| 179 | +The housekeeping is mostly file moves and doc edits. No tests to run, no CI to pass other than docs-lint. Suggested commit grouping (one PR, several commits): |
| 180 | + |
| 181 | +1. `docs(retro): v0.2 thin-wrapper pivot retrospective` |
| 182 | +2. `docs(planning): archive delivered specs and plans` |
| 183 | +3. `docs(planning): relocate 0.2.0 release notes to planning/releases/` |
| 184 | +4. `docs(planning): triage deferred-work — drop ruff/test-extra items, annotate pydantic-guard` |
| 185 | +5. `docs(claude): point at planning/archive, planning/retros, planning/releases` |
| 186 | + |
| 187 | +Memory edits land separately (they live outside the repo). |
| 188 | + |
| 189 | +## Acceptance |
| 190 | + |
| 191 | +- `planning/specs/` contains only this spec. |
| 192 | +- `planning/plans/` is empty. |
| 193 | +- `planning/retros/2026-06-04-v0.2-thin-wrapper-pivot.md` exists with the six sections. |
| 194 | +- `planning/releases/0.2.0.md` exists; the old spec path no longer does. |
| 195 | +- `planning/archive/specs/` contains 14 files; `planning/archive/plans/` contains 13. |
| 196 | +- `planning/deferred-work.md` has 3 open items (1 decoder cache + 2 in-progress for 0.3.0) and the existing closed section unchanged; the two dropped tooling items are gone. |
| 197 | +- `CLAUDE.md` "Where to find what" mentions `archive/`, `retros/`, `releases/`. |
| 198 | +- Auto-memory: `epic_2_complete.md` corrected; `workflow_superpowers_cutover.md` corrected; `release_0_2_0_shipped.md` added; `MEMORY.md` updated. |
0 commit comments