cross-project

name

cross-project

description

Stay focused on the project with the task in hand; recall another project's knowledge ONLY when the task actually needs it. When a task requires changing a shared dependency you own (a local composer/npm package in another repo), make the change IN that owning repo — commit, push, retag — then update and re-verify the consumer. Trigger: an edit is about to land inside a dependency directory, or a task can't be done without touching a package you maintain elsewhere.

Cross-project — fix it where it lives, then update the consumer

Default: focus on the current project. Do not drag in other projects' code or knowledge speculatively. Only when a task genuinely needs another project — most often a shared dependency you own — do you reach across, and even then you reach with discipline. This completes the global rule ("changes to a symlinked package are done in the package folder, committed and pushed there") with the tail it omits: retag → update the consumer → re-verify.

Detection — the one agnostic invariant (lead with this)

You are about to edit a file. Before editing, ask: does this path belong to a different git repo than the project root?

git -C "$(dirname "$FILE")" rev-parse --show-toplevel   # the owning repo of the file
git rev-parse --show-toplevel                            # the project you're working in

If they differ, the file lives in a dependency checkout, not its source — vendor/<pkg> or node_modules/<pkg> is not where the edit belongs. (How it got there is a detail — e.g. a composer repositories[].type=path/symlink, or an npm file:/link:/workspace dep. You don't need to enumerate them; the git-toplevel mismatch is the invariant.) Detection is hook-side: the advisory hooks/cross_project_edit_guard.sh runs this check on every Edit/Write and injects the cycle below when it fires; the verify_before_commit advisory is the backstop if it slips through.

The owning-repo cycle (the load-bearing part)

When the change must land in a package you own:

1. Switch to the owning repo and make the change there with the normal discipline — implement it, then run maestro:regression in that repo. Never patch the consumer's vendor// node_modules/ copy (it's overwritten on the next install — and it's not the source of truth).
2. Commit + push in the owning repo.
3. Retag / bump the version in the owning repo (a new release tag / composer.json/package.json version), so the consumer can pull a named version, not a floating ref.
4. Update the consumer: composer update <vendor/pkg> (or npm update <pkg> / reinstall) so the consumer's lockfile and checkout move to the new version.
5. Re-verify in the consumer: run maestro:regression in the consumer — the dependency bump is a change (the sizing hook computes its tier; the dependency-repo flag alone scores it ≥ T2) and the suite-run confirms nothing broke. Only then is the task done.

Recursion: if that package itself owns a sub-dependency that must change, the same cycle applies one level down (per the global rule — "the same rules apply").

Knowledge — recall and capture on demand (not a global store)

Cross-project gotchas (this package's quirks, breaking-change patterns, the consumer's integration constraints) are recalled and captured via taskmanager memories — kind: integration (or convention/architecture), scope.domains = <vendor/pkg> — using the existing memory protocol; no new store. Honest residual: memories live in each project's own .taskmanager DB, so a lesson about package X learned in consumer A is invisible from consumer B. Pragmatic mitigation: record a lesson about the package itself in the owning package's own .taskmanager DB, keyed by the package name — its natural shared home. (A global cross-project knowledge store is deliberately deferred until a repeated, concrete pain proves it — building it now is a drift-prone second source of truth.)

What this is NOT

• Not a re-router — it's a where-the-edit-lands modifier on whatever lane route already chose, orthogonal to scope/risk. (route only points here; the edit-time trigger above is the real entry.)
• Not a license to wander — the default is and stays the current project; you cross over only when the hook's toplevel check fires or the task names a package you own.
• Not a new gate — the consumer re-verify is the existing regression gate; nothing hard-blocks.
• Not a dependency-tree crawler — you touch only the package the task needs, not its whole graph.