Merge pull request #25 from modern-python/chore/pin-faststream-pre-0.7

chore: pin faststream <0.7 and adopt planning/ workflow

Author: lesnik512

CLAUDE.md

@@ -8,6 +8,17 @@ FastStream broker integration for Redis-backed distributed timer scheduling.
 - `just lint` — format and lint
 - `just install` — install deps
 
+## Workflow
+
+Per-feature workflow: brainstorming → spec in
+`planning/specs/YYYY-MM-DD-<slug>-design.md` → writing-plans →
+plan in `planning/plans/YYYY-MM-DD-<slug>-plan.md` →
+executing-plans / subagent-driven-development →
+requesting-code-review → finishing-a-development-branch.
+
+Topic slugs are kebab-case descriptions (e.g. `faststream-0.7-migration`),
+not story IDs.
+
 ## Tests
 
 - `tests/test_unit.py` — pure unit tests (no Redis required)

planning/plans/.gitkeep

@@ -0,0 +1,344 @@
+# FastStream 0.7 migration — PR1 (defensive pin + planning scaffold) Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Tighten the FastStream pin to `>=0.6,<0.7`, adopt `--cov-fail-under=100`, and scaffold the `planning/` workflow directory mirroring `faststream-outbox`. Lands the PR2 design doc in the same commit so PR2 has a home.
+
+**Architecture:** Pure config + docs change. No runtime code touched. Single commit on `chore/pin-faststream-pre-0.7`. The coverage gate is conditional: if `just test` is not at 100% today, the gate addition gets reverted and deferred to PR2 (recorded as decision in commit body).
+
+**Tech Stack:** `pyproject.toml`, `uv`, `pytest-cov`, markdown.
+
+**Related spec:** `planning/specs/2026-06-03-faststream-0.7-migration-design.md`.
+
+---
+
+## Task 1: Create the working branch
+
+**Files:** None (git operation).
+
+- [ ] **Step 1: Confirm clean tree**
+
+Run: `git status`
+Expected: `nothing to commit, working tree clean` (a fresh `planning/` dir from the brainstorming session is acceptable; we'll stage it later).
+
+- [ ] **Step 2: Create branch**
+
+Run: `git switch -c chore/pin-faststream-pre-0.7`
+Expected: `Switched to a new branch 'chore/pin-faststream-pre-0.7'`
+
+## Task 2: Establish coverage baseline (precondition for gate adoption)
+
+**Files:** None (read-only test run).
+
+The spec's R8 flags that adopting `--cov-fail-under=100` in PR1 requires the suite to already hit 100%. This task discovers the baseline.
+
+- [ ] **Step 1: Run full suite via Justfile**
+
+Run: `just test`
+Expected: All tests pass. Final coverage line at bottom of output shows total `%` covered.
+
+- [ ] **Step 2: Record baseline**
+
+Note the total coverage percentage from the report. There are three branches:
+
+- **If `100%`:** Continue to Task 3 — gate adoption is safe.
+- **If `<100%` AND missing lines are trivially testable:** Continue to Task 3 but write the backfill tests in Task 3a (insert before Task 4) before adding the gate.
+- **If `<100%` AND gaps are non-trivial:** Skip the gate adoption entirely; remove "adopt `--cov-fail-under=100`" from this PR's scope; record decision in commit body; gate moves to PR2 where the orphaned-branch removal naturally lifts coverage.
+
+## Task 3: Tighten the FastStream pin
+
+**Files:**
+- Modify: `pyproject.toml` (line 12)
+
+- [ ] **Step 1: Read current dependencies block**
+
+Run: `sed -n '9,14p' pyproject.toml`
+Expected output:
+```
+requires-python = ">=3.13,<4"
+license = "MIT"
+dependencies = [
+    "faststream~=0.6",
+    "redis>=5.0",
+]
+```
+
+- [ ] **Step 2: Edit the pin**
+
+Change `"faststream~=0.6"` to `"faststream>=0.6,<0.7"` on line 12.
+
+- [ ] **Step 3: Verify edit**
+
+Run: `grep -n "faststream" pyproject.toml | grep -v module`
+Expected: `12:    "faststream>=0.6,<0.7",`
+
+## Task 4: Adopt `--cov-fail-under=100` (conditional on Task 2)
+
+**Files:**
+- Modify: `pyproject.toml` (line 67)
+
+**Skip this task if Task 2 step 2 selected the third branch (`<100%`, non-trivial gaps).**
+
+- [ ] **Step 1: Read current pytest config**
+
+Run: `sed -n '66,70p' pyproject.toml`
+Expected output:
+```
+[tool.pytest.ini_options]
+addopts = "--cov=. --cov-report term-missing"
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+```
+
+- [ ] **Step 2: Append the coverage gate to addopts**
+
+Change `addopts = "--cov=. --cov-report term-missing"` to `addopts = "--cov=. --cov-report term-missing --cov-fail-under=100"`.
+
+- [ ] **Step 3: Verify edit**
+
+Run: `grep -n "addopts" pyproject.toml`
+Expected: `addopts = "--cov=. --cov-report term-missing --cov-fail-under=100"`
+
+## Task 5: Regenerate lockfile
+
+**Files:**
+- Touched (gitignored, not committed): `uv.lock`
+
+`uv.lock` is gitignored in this repo, so the file is local-only. The regeneration confirms the resolver is happy with the tightened pin.
+
+- [ ] **Step 1: Regenerate lock**
+
+Run: `uv lock`
+Expected: `Resolved N packages in <time>` with no error. The `faststream` line in `uv.lock` should resolve to a `0.6.x` version (verify by `grep '^name = "faststream"' -A 2 uv.lock`).
+
+- [ ] **Step 2: Sync environment**
+
+Run: `uv sync --all-extras --all-groups --frozen`
+Expected: Sync succeeds against the frozen lock.
+
+## Task 6: Verify the gate (re-run suite)
+
+**Files:** None.
+
+- [ ] **Step 1: Re-run full suite under the new gate**
+
+Run: `just test`
+Expected: All tests pass; if Task 4 ran, the final line is `Required test coverage of 100% reached`. If Task 4 was skipped, this is just a re-confirmation that the pin change didn't break anything.
+
+## Task 7: Scaffold `planning/` (likely already present from spec-writing)
+
+**Files:**
+- Create (if missing): `planning/specs/.gitkeep`
+- Create (if missing): `planning/plans/.gitkeep`
+
+- [ ] **Step 1: Check current state**
+
+Run: `ls -la planning/specs planning/plans 2>&1`
+Expected: Both directories already exist with `.gitkeep` files and a design doc in `planning/specs/`. (Created at spec-writing time.)
+
+- [ ] **Step 2: Touch any missing `.gitkeep` files**
+
+If either `.gitkeep` is missing:
+Run: `touch planning/specs/.gitkeep planning/plans/.gitkeep`
+
+## Task 8: Confirm design + plan docs are on disk
+
+**Files:**
+- Verify: `planning/specs/2026-06-03-faststream-0.7-migration-design.md`
+- Verify: `planning/plans/2026-06-03-faststream-0.7-migration-pr1-plan.md` (this file)
+- Verify: `planning/plans/2026-06-03-faststream-0.7-migration-pr2-plan.md`
+
+- [ ] **Step 1: List planning files**
+
+Run: `ls planning/specs planning/plans`
+Expected output:
+```
+planning/plans:
+.gitkeep
+2026-06-03-faststream-0.7-migration-pr1-plan.md
+2026-06-03-faststream-0.7-migration-pr2-plan.md
+
+planning/specs:
+.gitkeep
+2026-06-03-faststream-0.7-migration-design.md
+```
+
+## Task 9: Add `## Workflow` section to CLAUDE.md
+
+**Files:**
+- Modify: `CLAUDE.md`
+
+- [ ] **Step 1: Read current CLAUDE.md to confirm anchor**
+
+Run: `grep -n "^## " CLAUDE.md`
+Expected output:
+```
+5:## Commands
+11:## Tests
+```
+
+- [ ] **Step 2: Insert `## Workflow` between `## Commands` and `## Tests`**
+
+After the `## Commands` block (which ends with the `just install` line on line 9) and before the `## Tests` heading on line 11, insert this block (mind the leading blank line):
+
+```markdown
+
+## Workflow
+
+Per-feature workflow: brainstorming → spec in
+`planning/specs/YYYY-MM-DD-<slug>-design.md` → writing-plans →
+plan in `planning/plans/YYYY-MM-DD-<slug>-plan.md` →
+executing-plans / subagent-driven-development →
+requesting-code-review → finishing-a-development-branch.
+
+Topic slugs are kebab-case descriptions (e.g. `faststream-0.7-migration`),
+not story IDs.
+```
+
+- [ ] **Step 3: Verify section order**
+
+Run: `grep -n "^## " CLAUDE.md`
+Expected output:
+```
+5:## Commands
+11:## Workflow
+22:## Tests
+```
+(Line numbers approximate; the important thing is `## Workflow` appears between `## Commands` and `## Tests`.)
+
+## Task 10: Verify gitignore does not eat new plan files
+
+**Files:** None (read-only check).
+
+- [ ] **Step 1: Sanity check the gitignore rule**
+
+Run: `git check-ignore -v planning/plans/2026-06-03-faststream-0.7-migration-pr1-plan.md`
+Expected: exit code `1` (no output) — the file is NOT ignored.
+
+If exit code is `0` and output names `plan.md` as the rule: the gitignore rule is matching too aggressively (would surprise me but verify). In that case, edit `.gitignore` to anchor the rule: change the bare `plan.md` line to `/plan.md` so it only matches the root.
+
+## Task 11: Run lint
+
+**Files:** None.
+
+- [ ] **Step 1: Run lint**
+
+Run: `just lint`
+Expected: All four steps (`eof-fixer`, `ruff format`, `ruff check --fix`, `ty check`) green. Note: `eof-fixer` may auto-add newlines to `.gitkeep` or CLAUDE.md — re-stage afterward.
+
+## Task 12: Stage and commit
+
+**Files:** All modified/created files this PR.
+
+- [ ] **Step 1: Stage changes**
+
+Run:
+```
+git add pyproject.toml \
+        CLAUDE.md \
+        planning/
+```
+
+- [ ] **Step 2: Confirm staged files**
+
+Run: `git status --short`
+Expected output (order may vary):
+```
+M  CLAUDE.md
+M  pyproject.toml
+A  planning/plans/.gitkeep
+A  planning/plans/2026-06-03-faststream-0.7-migration-pr1-plan.md
+A  planning/plans/2026-06-03-faststream-0.7-migration-pr2-plan.md
+A  planning/specs/.gitkeep
+A  planning/specs/2026-06-03-faststream-0.7-migration-design.md
+```
+
+If `uv.lock` shows up in `git status` despite being gitignored, do **not** stage it — confirm `.gitignore` still lists `uv.lock`.
+
+- [ ] **Step 3: Verify no per-call kwarg accidentally landed**
+
+Run: `git diff --cached pyproject.toml`
+Expected: only the two single-line edits (pin + addopts).
+
+- [ ] **Step 4: Commit**
+
+```bash
+git commit -m "$(cat <<'EOF'
+chore: pin faststream <0.7 and adopt planning/ workflow
+
+- pyproject.toml: faststream~=0.6 -> >=0.6,<0.7. Explicit upper bound
+  makes intent visible and lets the 0.7 migration land in a feature
+  branch without users pulling unfinished work.
+- pyproject.toml: addopts adds --cov-fail-under=100 (matches sister
+  faststream-outbox project). Hardens the coverage gate before the
+  0.7 migration (PR2) removes branches.
+- planning/: scaffold planning/specs/ + planning/plans/ with .gitkeep
+  files; mirrors the sister faststream-outbox layout. Includes the
+  faststream-0.7 migration design and the two plan files so PR2 has
+  a home.
+- CLAUDE.md: new ## Workflow section pointing at the planning/ layout.
+
+Companion PR migrates to faststream 0.7 and drops 0.6 support
+(>=0.7,<0.8).
+EOF
+)"
+```
+
+(If Task 4 was skipped, drop the `--cov-fail-under=100` bullet from the body.)
+
+- [ ] **Step 5: Verify commit**
+
+Run: `git log -1 --stat`
+Expected: single commit with the message above and the staged files.
+
+## Task 13: Push and open PR
+
+**Files:** None (git remote operation).
+
+- [ ] **Step 1: Push branch**
+
+Run: `git push -u origin chore/pin-faststream-pre-0.7`
+Expected: `* [new branch]` line and a hint URL for opening the PR.
+
+- [ ] **Step 2: Open PR via gh**
+
+```bash
+gh pr create --title "chore: pin faststream <0.7 and adopt planning/ workflow" --body "$(cat <<'EOF'
+## Summary
+
+- Tightens the FastStream pin from `~=0.6` to `>=0.6,<0.7`. The companion PR migrates to 0.7 and drops 0.6 support.
+- Adopts `--cov-fail-under=100` (matches sister `faststream-outbox` project).
+- Scaffolds `planning/specs/` and `planning/plans/` and lands the 0.7 migration design + two-PR plan files.
+
+## Test plan
+
+- [ ] `just lint` passes
+- [ ] `just test` passes at 100% coverage
+- [ ] `planning/specs/` and `planning/plans/` are tracked by git
+- [ ] `CLAUDE.md` shows the new `## Workflow` section between `## Commands` and `## Tests`
+EOF
+)"
+```
+
+(If Task 4 was skipped: drop the second bullet of the Summary block.)
+
+- [ ] **Step 3: Note PR URL**
+
+The `gh pr create` command outputs the PR URL. Record it for the user.
+
+---
+
+## Verification (acceptance gate)
+
+The PR is done iff:
+
+- [ ] `git diff main..chore/pin-faststream-pre-0.7 -- pyproject.toml` shows only the pin edit and (if applicable) the `--cov-fail-under=100` addition.
+- [ ] `git grep -n "faststream~=0.6"` returns nothing on the branch.
+- [ ] `planning/specs/2026-06-03-faststream-0.7-migration-design.md` exists and is tracked.
+- [ ] `planning/plans/2026-06-03-faststream-0.7-migration-pr1-plan.md` (this file) exists and is tracked.
+- [ ] `planning/plans/2026-06-03-faststream-0.7-migration-pr2-plan.md` exists and is tracked.
+- [ ] `planning/specs/.gitkeep` and `planning/plans/.gitkeep` exist and are tracked.
+- [ ] `CLAUDE.md` contains the `## Workflow` section between `## Commands` and `## Tests`.
+- [ ] `just lint` clean on the branch tip.
+- [ ] `just test` green (at 100% if Task 4 ran).
+- [ ] PR is open with the prescribed title and body.