Skip to content

Commit c650b5e

Browse files
lesnik512claude
andcommitted
docs(spec): v0.2 retro + housekeeping bundle design
Drives the close-out work for the v0.2 thin-wrapper pivot: written retrospective, planning/ archive layout, deferred-work triage, and auto-memory updates. Code changes (pydantic-as-extra) ship separately in a 0.3.0 follow-up spec. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
1 parent 3edef19 commit c650b5e

1 file changed

Lines changed: 198 additions & 0 deletions

File tree

Lines changed: 198 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,198 @@
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

Comments
 (0)