build: a worktree under .claude/worktrees/ breaks every AUTOMOC target with -Wshadow-header

[Yaraslaut]

What happens

Configuring and building this repository from a git worktree placed inside
the repository (.claude/worktrees/<name>/, which is where the agent harness
puts them) fails every Qt AUTOMOC target under -Weverything -Werror:

$ cmake --build build/ladder-srv --target ladder_ledger_tests -j 8
FAILED: [code=1] examples/ledger/CMakeFiles/ladder_ledger_gui_lib.dir/ladder_ledger_gui_lib_autogen/mocs_compilation.cpp.o
.../build/ladder-srv/examples/ledger/ladder_ledger_gui_lib_autogen/BZS2EH3DBT/moc_budget_presenter.cpp:9:10: error:
  multiple candidates for header '../../../../../../examples/ledger/gui_lib/budget_presenter.hpp' found;
  directory '.../build/ladder-srv/examples/ledger/ladder_ledger_gui_lib_autogen/BZS2EH3DBT/../../../../../../examples/ledger/gui_lib'
  chosen, ignoring others including '/home/yaraslau/repo/morph/.claude/worktrees/agent-a99217a5bca2f10a4/examples/ledger/include'
  [-Werror,-Wshadow-header]
    9 | #include "../../../../../../examples/ledger/gui_lib/budget_presenter.hpp"
      |          ^
8 errors generated.

Eight such errors for ladder_ledger_gui_lib (one per moc'd class), and the
same for ladder_pastebin_gui_lib — every rung with a gui_lib/.

Why

moc emits its include as a path relative to the build tree, with enough ..
segments to climb back to the source root. clang resolves that relative path
against every -I directory as well, and one of them is
<worktree>/examples/<rung>/include. Climbing six levels from there escapes the
worktree entirely:

/home/yaraslau/repo/morph/.claude/worktrees/agent-XXXX/examples/ledger/include
  + ../../../../../..  ->  /home/yaraslau/repo/morph
  + examples/ledger/gui_lib/budget_presenter.hpp   <- exists, in the MAIN checkout

so a second, different-but-identically-named candidate really is on the search
path, and clang's -Wshadow-header fires. In a plain checkout the same climb
lands somewhere that does not exist, there is one candidate, and nothing is
reported. The nesting of .claude/worktrees/ inside the repository is what
makes the escaped path resolve.

Verification status

Reproduced, on worktree-agent-a99217a5bca2f10a4 (base commit 2a035fe8),
Arch Linux, clang version 22.1.8, Qt6, preset clang-release with
-DMORPH_BUILD_LADDER=ON -DMORPH_LADDER_RUNGS=all -DMORPH_BUILD_NET=ON -DMORPH_BUILD_QT=ON -DMORPH_BUILD_TESTS=ON. Output above is the real compiler
output, trimmed only for width.

Not verified: that a plain (non-nested) checkout builds these targets on
this machine — no non-worktree build of ladder_*_gui_lib was performed here.
The mechanism above says it should, and no ladder_*_tests binary exists in any
of the main checkout's build trees to contradict or confirm it. Not verified on
any other clang version; -Wshadow-header is recent, so older clangs are
probably unaffected.

Not caused by the branch: no gui_lib/ source is touched by the work this
was found under (a fix for morph#367, which only touches
examples/ledger/src/models/ledger_model.cpp and tests).

Impact

Any agent or contributor working in a worktree under .claude/worktrees/ cannot
build a rung's test binary at all, because ladder_<rung>_tests links
ladder_<rung>_gui_lib when MORPH_BUILD_QT=ON. The workaround used for #367
was a second build directory configured with
-DMORPH_ENABLE_STRICT_COMPILATION=OFF, which drops -Werror and lets the
diagnostic through as a warning — at the cost of not compiling the tests under
the project's real warning set.

Options

• Add -Wno-shadow-header to the AUTOMOC targets' warning set (it diagnoses a
  build-layout coincidence here, not anything about the code).
• Or put worktrees outside the repository, if the harness can be told to.
• Or set CMAKE_AUTOMOC_PATH_PREFIX/an absolute moc include so the emitted
  path does not climb.

What would change the verdict

Close it when a rung's ladder_<rung>_tests builds clean under the project's
own strict warning set from a worktree at .claude/worktrees/<name>/. Re-open
if a newer clang extends -Wshadow-header to a case a plain checkout also hits.

[Yaraslaut]

#376 is the same defect, filed independently from a sibling worktree in the same batch. It adds two measurements this report does not have: realpath of the shadowing candidate resolving into the outer checkout, and the same moc TU compiling clean when built from the top-level checkout rather than the nested worktree.

Both were hit while building ladder_*_gui_lib targets (bookmarks, kanban, ledger), which is independent corroboration that it is not rung-specific.

[Yaraslaut]

Absorbing #376's evidence here before closing it as a duplicate.

The two measurements #376 adds (both stated there as measured, not inferred; clang 22.1.8, Qt 6.11.2 moc, clang-release preset, MORPH_BUILD_QT=ON, strict compilation at its default ON):

1. The same generated moc TU, compiled with the same flags but with the top-level checkout's -I paths, compiles clean (exit=0). So the cause is the path nesting, not the clang version and not the moc output.
2. realpath of the shadowing candidate resolves into the outer checkout — /home/yaraslau/repo/morph/examples/kanban/gui_lib/board_presenter.hpp — and that file exists.

The full diagnostic, as emitted:

FAILED: examples/kanban/CMakeFiles/ladder_kanban_gui_lib.dir/ladder_kanban_gui_lib_autogen/mocs_compilation.cpp.o
.../ladder_kanban_gui_lib_autogen/BZS2EH3DBT/moc_board_presenter.cpp:9:10:
error: multiple candidates for header '../../../../../../examples/kanban/gui_lib/board_presenter.hpp' found;
directory '.../BZS2EH3DBT/../../../../../../examples/kanban/gui_lib' chosen,
ignoring others including '/home/.../worktrees/agent-xxxx/examples/kanban/include'
[-Werror,-Wshadow-header]

Scope, measured across three independent sessions: ladder_kanban_gui_lib, ladder_bookmarks_gui_lib and ladder_pastebin_gui_lib all hit it, so it is every rung with a gui_lib — and with them every ladder_<rung>_tests binary, which links that library. The non-Qt targets (ladder_<rung>_server, ladder_<rung>_lib) build fine in a nested worktree; only AUTOMOC-generated TUs carry the ascending relative include.

Also not verified (from #376): whether older clang releases carry -Wshadow-header at all, whether GCC has an equivalent diagnostic, and whether a worktree placed outside the repository avoids it — inferred yes from the mechanism, not measured.

Impact worth restating: the workaround all three sessions reached for was a second build directory with -DMORPH_ENABLE_STRICT_COMPILATION=OFF, which silences -Werror for the whole tree. That is why #380 and #381 both have to record that their test binaries were not compiled under the strict warning set — this issue is directly costing verification coverage on unrelated fixes.

[Yaraslaut]

Triage: rescope — mechanism reproduced from first principles, with a control; but the first listed option is the unsafe one

Premise: confirmed, and the "not verified" item with it. Reproduced the diagnostic with no Qt, no CMake and no morph — just two checkouts' worth of directories, a hand-written moc-shaped include at the real depth, and one -I:

$ clang++ -fsyntax-only -Wshadow-header -Werror -I <root>/.claude/worktrees/wt/examples/ledger/include \
      <root>/.claude/worktrees/wt/build/ladder-srv/examples/ledger/ladder_ledger_gui_lib_autogen/BZS2EH3DBT/moc_budget_presenter.cpp

error: multiple candidates for header '../../../../../../examples/ledger/gui_lib/budget_presenter.hpp' found;
directory '…/wt/build/ladder-srv/examples/ledger/ladder_ledger_gui_lib_autogen/BZS2EH3DBT/../../../../../../examples/ledger/gui_lib'
chosen, ignoring others including '…/wt/examples/ledger/include' [-Werror,-Wshadow-header]

Control, same layout with the worktree outside the repository: clean, exit 0. So the nesting is the whole cause, exactly as the issue's mechanism section says, and the six .. segments matter — at any other depth the escaped path does not resolve and nothing is reported. clang 22.1.8, same as the report.

The reason to rescope: -Wno-shadow-header hides a real failure, not just a layout coincidence

The issue calls the diagnostic "a build-layout coincidence here, not anything about the code" and lists suppression first. Measured otherwise. Deleting the worktree's copy of the header — the state a branch produces whenever it adds, renames or moves a header under gui_lib/, since the other checkout still has the old one — and compiling with the warning suppressed:

$ clang++ -fsyntax-only -Wno-shadow-header -I <wt>/examples/ledger/include <moc dir>/probe.cpp
COMPILED: the MAIN checkout's header was silently used from inside the worktree

The probe calls a function defined only in the main checkout's copy, and it links the declaration successfully. So in this layout the -I climb is a live path from one checkout into another, and -Wshadow-header is the only thing that reports it. Suppressing it does not remove a false positive; it removes the sole signal for a genuine cross-checkout header pickup — a control that stops measuring, which is the failure mode IMPLEMENTATION.md's own instincts about gates are meant to catch.

Reorder the options accordingly. The two that remove the ambiguity rather than the diagnostic should lead:

• worktrees outside the repository (removes the escape path entirely — confirmed by the control above);
• CMAKE_AUTOMOC_PATH_PREFIX / an absolute moc include, so the emitted path does not climb (plausible from the mechanism; not tested here — worth verifying before committing to it, since it changes every AUTOMOC target's generated includes).

-Wno-shadow-header should be listed last and explicitly as the option that trades a real signal away, if it is kept at all.

Everything else stands. The impact section is right — ladder_<rung>_tests links ladder_<rung>_gui_lib under MORPH_BUILD_QT=ON, so an agent in a nested worktree cannot build a rung's tests under the project's real warning set (-Weverything -Werror per cmake/compiler_options.cmake:112-114), and the -DMORPH_ENABLE_STRICT_COMPILATION=OFF workaround means those tests compile under a different warning set from the one CI enforces.

What would change this verdict: evidence that the chosen candidate can never be the wrong checkout's file — e.g. that AUTOMOC's -I set cannot reach a sibling checkout when the intended header is missing. The probe above reaches it.