## TL;DR
npm update at the root re-hoisted the tree and workspaces that relied on the old layout broke. Reinstall at the root to settle the tree, then update per workspace with the workspace flag so each workspace gets an explicit, reviewed change.

## Error
```text
agent ran npm update in the workspace root  -  hoisting moved the dep and three workspaces broke
```

## Steps
1. Confirm hoisting is the cause: check which workspace packages fail and whether the dependency moved from their local node_modules to the root.
   Expected output: The failing workspaces expected the dep at their old hoisted location.
2. Run npm install at the root to produce a clean, consistent tree, then re-run the workspace tests.
   Expected output: You know whether a clean install alone fixes the breakage.
3. Redo the update per workspace (npm update -w [workspace name]) instead of at the root, reviewing each workspace's diff.
   Expected output: Each workspace change is explicit and independently testable.
4. Consider pinning the layout: set install-strategy or hoisting options in .npmrc if your workspaces need a stable tree.
   Expected output: Future root installs cannot silently relocate the dep.
5. Forbid root-level npm update in the agent's instructions; updates happen per workspace.
   Expected output: The agent has one sanctioned update path.

## When to use
- Workspaces break right after a root-level npm update
- A dependency moved between root and workspace node_modules
- You are writing npm workspace rules for an agent

## When not to use
- A version bump that breaks workspaces by API change; that is compatibility, not hoisting
- Phantom-dependency bugs in a single package; fix the imports
- pnpm or yarn workspaces; their hoisting rules differ

### Variant phrasings
#### npm update at root broke workspace packages
#### hoisting moved a dependency and workspaces fail
#### update a single npm workspace without touching the root

## Why it happens
npm hoists shared dependencies to the root to dedupe, and the exact layout is an implementation detail that changes between versions. Workspace code that (directly or transitively) relied on the old layout breaks when the update re-hoists, even though no version in the workspace's own manifest changed.

## Edge cases
- A clean root install can paper over the problem until the next update; the per-workspace rule is the real fix.
- Workspace bin links can also move; check scripts that call workspace binaries by path.
- Lockfile churn from a root update touches every workspace; review it as carefully as the code.

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_IPtL-fbqiMahq5ZEnVbOxg