docs(multi-agent): symlinked vendor loads the sibling worktree's src - #89
Merged
Conversation
Composer writes $baseDir into autoload_psr4.php by resolving __DIR__, which follows a symlink. A worktree whose vendor/ points at a sibling therefore autoloads that sibling's src/, silently: tests and static analysis run green or red against code that is not being edited. The failure presents as a broken fix rather than a broken environment, so it costs a debugging round before anyone suspects the setup. Adds a one-line detection via ReflectionClass::getFileName(), the hardlink alternative that keeps $baseDir local, and a line for the briefing template. Signed-off-by: Sebastian Mendel <github@sebastianmendel.de>
Contributor
Dependency Review✅ No vulnerabilities or license issues or OpenSSF Scorecard issues found.Scanned FilesNone |
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
github-actions
Bot
added
documentation
There was a problem hiding this comment.
Pull request overview
Adds a new documented pitfall (“Hazard 8”) to the php-modernization skill’s multi-agent guidance, warning that symlinking vendor/ across sibling git worktrees can silently cause the Composer autoloader to resolve the other worktree’s src/, leading to misleading test/static-analysis results.
Changes:
- Document Hazard 8: how a symlinked
vendor/can make autoloading point at a sibling worktree’s source tree. - Provide a quick detection approach and rank safer worktree setups (separate install, hardlinks, symlink-only-when-not-executing).
- Extend the concise multi-agent briefing template with a one-line “don’t symlink vendor/” warning + verification hint.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
The example class read as if it existed; pasted verbatim it throws a ReflectionException, which undermines a check meant to take one line. Say to substitute any real class from the project's own src/ — the probe asks where a class resolves from, so any autoloadable one answers it — and keep the command on a single line. Signed-off-by: Sebastian Mendel <github@sebastianmendel.de>
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Came from /retro: yes
Adds
Hazard 8tomulti-agent-pitfalls.md.Giving a second git worktree its own
vendor/costs a fullcomposer install, so symlinking the sibling's looks like a free shortcut. It is not. Composer writes$baseDir = dirname(dirname(__DIR__))intovendor/composer/autoload_psr4.php, and__DIR__resolves through the symlink — so$baseDirpoints at the other worktree and everyApp\…class loads from that tree'ssrc/.Nothing errors. Tests and PHPStan run happily against code that is not being edited. In the session this came from, a correct guard was investigated as defective because the test exercising it was executing the sibling worktree's older copy — the symptom reads as a broken fix, not a broken environment, which is what makes it expensive.
The hazard adds a one-line detection (
ReflectionClass::getFileName()before trusting any result in a fresh worktree), and ranks the three setups: realcomposer installper worktree,cp -alhardlinks (cheap, and$baseDirstays local becausevendor/is a real directory), symlink only where nothing is executed. Plus one line in the briefing template.Sibling of the existing Hazard 4 — that one is the wrong dependency version after a rebase, this one the wrong source tree. Hazard 2 (
git checkout --outside scope) is adjacent but a different mechanism; the general git rule for that goes to git-workflow-skill#138.No
SKILL.mdchange, so the 500-word budget is untouched.