diff --git a/.gitignore b/.gitignore
index e795766..3b0adae 100644
--- a/.gitignore
+++ b/.gitignore
@@ -42,5 +42,10 @@ coverage/
 .opencode/
 .sisyphus/
 
+# Worktrees Claude Code creates for parallel sessions and isolated subagents.
+# Only this subdirectory: the rest of `.claude/` is tracked, because the rules
+# under it are part of the repository.
+.claude/worktrees/
+
 # Local development path wiring (never committed; breaks CI which has no sibling paths)
 pubspec_overrides.yaml
diff --git a/.worktreeinclude b/.worktreeinclude
new file mode 100644
index 0000000..f6e463c
--- /dev/null
+++ b/.worktreeinclude
@@ -0,0 +1,22 @@
+# Gitignored files copied into every worktree Claude Code creates, for `--worktree`,
+# for `EnterWorktree`, and for a subagent with `isolation: worktree`.
+#
+# A worktree is a fresh checkout, so `pubspec_overrides.yaml` is absent from it, and
+# its absence fails silently rather than loudly: the siblings resolve from pub.dev
+# instead of the working trees beside this one, `flutter pub get` succeeds, and the
+# suite then passes against the PUBLISHED packages while you are reading a diff of
+# the local ones. An unreleased sibling API is the case where that bites.
+#
+# `.gitignore` syntax, and only files that match AND are gitignored are copied, so a
+# tracked file can never be duplicated by this list.
+#
+# The paths inside `pubspec_overrides.yaml` have to be ABSOLUTE for this to work.
+# Worktrees live under `.claude/worktrees/<slug>`, so a relative `../magic` resolves
+# to `.claude/worktrees/magic`, which does not exist, and version solving fails on
+# the first path dependency. CI writes its own copy of that file with relative paths
+# and is unaffected, because there the siblings really do sit beside the checkout.
+#
+# NOT processed when a WorktreeCreate hook replaces the default git logic; such a
+# hook has to copy these itself. This project has no such hook.
+
+pubspec_overrides.yaml