From a75d9ed98cbf8a8c78e95e5778ce920963554011 Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 4 May 2026 01:07:07 +0000 Subject: [PATCH 1/3] =?UTF-8?q?docs(migration):=20anchor=20v3=E2=86=92v4?= =?UTF-8?q?=20adopter=20numbers=20to=20v4.0=20release,=20point=20to=20live?= =?UTF-8?q?=20codemod?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The "270 files / 161 test-collection failures" paragraph read as a current migration-difficulty forecast; it is actually a v4.0-era worst-case baseline. v4.3+ alias coverage and codemod improvements have materially reduced finding counts. Adds temporal context and redirects adopters to run the codemod against their own tree for a current estimate, so the note ages gracefully without becoming a second stale number. Closes #520 https://claude.ai/code/session_0138z8359JAkARZJWfmBLprE --- MIGRATION_v3_to_v4.md | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/MIGRATION_v3_to_v4.md b/MIGRATION_v3_to_v4.md index 7b406e56c..751aba706 100644 --- a/MIGRATION_v3_to_v4.md +++ b/MIGRATION_v3_to_v4.md @@ -48,10 +48,13 @@ dependencies = [ ## Fix removed-type imports first — they cascade -Real-adopter feedback (salesagent v3→v4 experiment, 270 files scanned, 161 -test-collection failures): consumers tend to centralize SDK imports in one -schema module, so a single broken import there crashes test collection across -the whole codebase. salesagent re-exported through `src/core/schemas/_base.py` +Real-adopter feedback (salesagent v3→v4 experiment at v4.0 release, 270 files +scanned, 161 test-collection failures — these figures reflect tooling at +initial release, before alias coverage and codemod improvements; run the +codemod against your own tree to see your actual count): consumers tend to +centralize SDK imports in one schema module, so a single broken import there +crashes test collection across the whole codebase. salesagent re-exported +through `src/core/schemas/_base.py` — **one missing `FormatCategory` import there cascaded into ~140 test failures during pytest collect-only**, and stubbing it revealed the next ~140-test cascade from `BrandManifest`, then the next from the `generated_poc` reach-ins. From c01742f577581cc8d7ca9b3bbb6710870f39351e Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 4 May 2026 01:08:42 +0000 Subject: [PATCH 2/3] docs(migration): restructure adopter-feedback paragraph for clarity MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Pull figures outside the parenthetical and make the disclaimer a standalone sentence — resolves pre-PR review finding that em-dash + semicolon nested inside a parenthetical was hard to parse (human and agent readers both). No meaning change; intent and all data points preserved. https://claude.ai/code/session_0138z8359JAkARZJWfmBLprE --- MIGRATION_v3_to_v4.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/MIGRATION_v3_to_v4.md b/MIGRATION_v3_to_v4.md index 751aba706..4e3d35fa1 100644 --- a/MIGRATION_v3_to_v4.md +++ b/MIGRATION_v3_to_v4.md @@ -48,16 +48,16 @@ dependencies = [ ## Fix removed-type imports first — they cascade -Real-adopter feedback (salesagent v3→v4 experiment at v4.0 release, 270 files -scanned, 161 test-collection failures — these figures reflect tooling at -initial release, before alias coverage and codemod improvements; run the -codemod against your own tree to see your actual count): consumers tend to -centralize SDK imports in one schema module, so a single broken import there -crashes test collection across the whole codebase. salesagent re-exported -through `src/core/schemas/_base.py` -— **one missing `FormatCategory` import there cascaded into ~140 test failures -during pytest collect-only**, and stubbing it revealed the next ~140-test -cascade from `BrandManifest`, then the next from the `generated_poc` reach-ins. +Real-adopter feedback (salesagent v3→v4 experiment at v4.0 release): 270 files +scanned, 161 test-collection failures. These figures reflect tooling at initial +release, before alias coverage and codemod improvements; run the codemod against +your own tree to see your actual count. Consumers tend to centralize SDK imports +in one schema module, so a single broken import there crashes test collection +across the whole codebase. salesagent re-exported through +`src/core/schemas/_base.py` — **one missing `FormatCategory` import there +cascaded into ~140 test failures during pytest collect-only**, and stubbing it +revealed the next ~140-test cascade from `BrandManifest`, then the next from +the `generated_poc` reach-ins. The codemod's static finding count understates this by 100x+. To minimize the felt blast radius, work in this order: From 62477e9d2319fe7c7feca3dbab46d55371205416 Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 4 May 2026 01:09:58 +0000 Subject: [PATCH 3/3] docs(migration): clarify 'subsequent' improvements in adopter-feedback note Nit from pre-PR review: 'before alias coverage and codemod improvements' was vague about timing. 'Before subsequent' makes the temporal arc explicit. https://claude.ai/code/session_0138z8359JAkARZJWfmBLprE --- MIGRATION_v3_to_v4.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/MIGRATION_v3_to_v4.md b/MIGRATION_v3_to_v4.md index 4e3d35fa1..07840d04c 100644 --- a/MIGRATION_v3_to_v4.md +++ b/MIGRATION_v3_to_v4.md @@ -50,7 +50,7 @@ dependencies = [ Real-adopter feedback (salesagent v3→v4 experiment at v4.0 release): 270 files scanned, 161 test-collection failures. These figures reflect tooling at initial -release, before alias coverage and codemod improvements; run the codemod against +release, before subsequent alias coverage and codemod improvements; run the codemod against your own tree to see your actual count. Consumers tend to centralize SDK imports in one schema module, so a single broken import there crashes test collection across the whole codebase. salesagent re-exported through