Skip to content

Drop the ADR count claim; give pytest<10 a stated release condition - #20

Merged
AdamClemens merged 1 commit into
mainfrom
fix/adr-count-and-pytest-bdd-watch
Aug 23, 2026
Merged

Drop the ADR count claim; give pytest<10 a stated release condition#20
AdamClemens merged 1 commit into
mainfrom
fix/adr-count-and-pytest-bdd-watch

Conversation

@AdamClemens

Copy link
Copy Markdown
Owner

Two small corrections, one worth more than its size. Documentation only — no code changed, and TASK-018 deliberately not started.

1. The merge gate's first miss

adr/CLAUDE.md read:

Six exist: ADR-001ADR-006 — all Accepted. The next number is 007.

That was wrong within hours of being written. ADR-007 landed in the very change that introduced the merge gate requiring exactly this kind of restatement to be updated in the same branch. The gate's own first application missed it.

Nothing mechanical was going to catch it. check-references sees paths that don't resolve, and a count is not a path. check-claims reports completeness claims about files, not tallies.

So the count is gone rather than corrected. That paragraph now points at docs/index.md's ADR section — generated from the tree, checked in CI — and states the next number as a rule ("one past the highest that exists there") rather than a value.

Correcting "Six" to "Seven" would have reset the drift by one and left the class of defect in place. The reasoning is the one docs/CLAUDE.md already gives for the index, the dependency tree and the inventory: a hand-written count sitting next to a generated listing of the same thing is a liability, not a convenience.

The blast-radius grep found exactly one such ADR count claim in the repository — the only reason this was one line rather than a sweep.

2. pytest<10 now has a release condition

docs/practices.md's tooling dependency update policy gains a Standing watch items subsection. A pin dodging a known upstream defect is a different animal from an ordinary version choice: it has a specific condition that releases it, and with nowhere to record that condition it becomes a pin nobody remembers the reason for.

The entry records what was verified, not assumed:

  • pytest-bdd 8.1.0 (still the latest release) passes nodeid/baseid to pytest's _register_fixture/FixtureDef.
  • A scenario run under -W error::pytest.PytestRemovedIn10Warning fails rather than warns; it passes normally only because warnings aren't errors here.
  • Why it matters more than a usual pin: since ADR-007, feature files are the acceptance criteria for Stage 4+ work, so the failure mode is not "some tests break" but "the acceptance criteria stop executing".

Upstream status, newly checked: issue #823 is open, and PR #827 (fix: avoid deprecated nodeid argument to _register_fixture) is open as of 2026-08-05. That's a materially better position than ADR-007 could state when it was written, and makes "stay pinned" the obvious option rather than a hopeful one.

Trigger to unpin is checkable: run that command against a released pytest-bdd containing #827 and expect a pass.

Merge-gate statement

  1. Mechanically greenmake ci clean locally (337 tests, all eleven gates); CI on this push.
  2. Internally consistent — blast radius grepped for both changes. One file carried the ADR count; nothing outside practices.md restates the tooling policy. check-claims returns only its five known false positives.
  3. Intent met — with a caveat worth stating. Neither change is machine-checked, and neither can be. The count fix works by removing the restatement, so there is nothing left to go stale — structural rather than tested. The watch item is prose whose value depends on someone reading it at the next dependency review.
  4. Said honestly: point 3 is the weakest part of this branch, and it is weak in the way the merge gate predicts rather than in a way it catches.

🤖 Generated with Claude Code

Two small corrections, one worth more than its size.

adr/CLAUDE.md read "Six exist: ADR-001 ... ADR-006 -- all Accepted. The
next number is 007." That was wrong within hours of being read: ADR-007
landed in the very change that introduced the merge gate requiring
exactly this kind of restatement to be updated in the same branch. The
gate's own first application missed it.

Nothing mechanical was going to catch it -- check-references sees paths
that do not resolve and a count is not a path; check-claims reports
completeness claims about files, not tallies. So the count is gone
rather than corrected. That paragraph now points at docs/index.md's ADR
section, which is generated and checked in CI, and states the next
number as a rule ("one past the highest that exists there") rather than
a value. Correcting "Six" to "Seven" would have reset the drift by one
and left the class of defect in place; the reasoning is the one
docs/CLAUDE.md already gives for the index, dependency tree and
inventory. The blast-radius grep found exactly one such ADR count claim
in the repository, which is the only reason this was one line rather
than a sweep.

Second: practices.md's tooling dependency update policy gains a
"Standing watch items" subsection, and pytest<10 is its first entry. A
pin dodging a known upstream defect is different from an ordinary
version choice -- it has a specific condition that releases it, and with
nowhere to record that condition it becomes a pin nobody remembers the
reason for.

The entry records what was verified rather than assumed: pytest-bdd
8.1.0 (still latest) passes nodeid/baseid to pytest's
_register_fixture/FixtureDef; a scenario run under
-W error::PytestRemovedIn10Warning fails rather than warns; it passes
normally only because warnings are not errors here. Upstream has
acknowledged it -- issue #823 open, and PR #827 ("fix: avoid deprecated
nodeid argument to _register_fixture") open as of 2026-08-05 -- which is
a better position than ADR-007 could state when written, and makes
"stay pinned" the obvious option rather than a hopeful one. Trigger to
unpin is checkable: run that command against a released pytest-bdd
containing #827 and expect a pass.

make ci clean: 337 tests, all eleven gates. check-claims returns only
its five known false positives. Documentation only; no code changed and
TASK-018 deliberately not started.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@AdamClemens
AdamClemens merged commit dde56e7 into main Aug 23, 2026
2 checks passed
@AdamClemens
AdamClemens deleted the fix/adr-count-and-pytest-bdd-watch branch August 23, 2026 14:18
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant