/update-deps

name: update-deps
description: Remediates dependencies in place of Dependabot version and security updates. Discovers outdated packages and open security advisories, resolves advisories (in-range refresh, chain-head bump, security-floor override, or alert dismissal), audits overrides, applies migrations for major bumps, and runs the quality gate. Trigger when the user clicks the statusline `📦 /update-deps` indicator or asks "update dependencies", "bump deps", "run dependabot", "fix Dependabot alerts", "fix security advisories".

Contents: Pre-flight: Worktree check; Pre-flight: Branch check; Package layout; Flags and run modes; Companion groups; Phase 1: Discover, preview, decide (orchestrator); Branch creation (after discovery); Override audit + Wave A: Haiku agent; Phase 5: Wave B (per-group major bumps); Phase 5b: Transitive refresh (Haiku agent); Phase 5c: Security resolutions; Phase 6: Post-update override audit; Phase 7: Final report; Phase 8: Publish; Cost record (run end).

Dependency remediation (outdated packages and security advisories) through one quality gate, in one record. Interactively it previews first, advisories ranked first, so you can snooze what you are not ready for. Run from the main checkout, on `main`/`master` or any other branch, it works in its own worktree on its own branch cut from the default branch, opens the PR, merges it once checks are green, then cleans up locally, leaving the branch the main checkout holds as it was.

Pre-flight: Worktree check

This wrapper writes a new `pnpm-lock.yaml` and opens a PR, which belong on the main checkout (the clone's primary working directory, on any branch) or in this command's own update worktree, not a per-SPEC worktree branch. The guard keeps the command out of every other linked worktree, rejecting hard with a message that surfaces the cached state from main so the user knows whether action is even pending. It admits only the command's own `deps/` update worktree, so a re-run continues there.

Detection (run this first, before anything else):

. .gaia/scripts/main-only-lib.sh
. .gaia/scripts/update-state-line-lib.sh
gaia_refuse_if_worktree "/update-deps" gaia_update_deps_state_line "deps/" || exit 1

Pre-flight: Branch check

Decide the run mode in this order. The first matching mode wins.

1. **Inside its own update worktree.** Read the branch with `git branch --show-current`. When it starts `deps/` and `bash .gaia/scripts/main-root-lib.sh --is-worktree` exits 0, this is a worktree run in place. Set `SHOULD_CREATE_WORKTREE=false`. Read `<worktree path>` with `git rev-parse --show-toplevel` and `<main checkout path>` with `bash .gaia/scripts/main-root-lib.sh`, each carried as a literal. Wait for provisioning before discovery, because the session-start hook re-provisions the tree on every entry:

   bash .gaia/scripts/provision-wait.sh --tree <worktree path>

Handle the result as `references/worktree.md` step 4 does, with one difference: this run did not create the tree, so exit 3 (`INSTALL_FAILED`) is reported and the run continues. Discovery reads this worktree's manifests. The run creates no worktree, publishes as a worktree run (the PR is opened or reused, merged when green, and cleaned up by path). 2. **In the main checkout, on `main`, `master` or any other branch.** The worktree is cut from the default branch on `origin` whichever branch the main checkout holds, so a run started on a feature branch publishes its own `deps/` pull request and leaves that branch, its files and its `node_modules` as they were. Set `SHOULD_CREATE_WORKTREE=true` but **do not create the worktree yet**: creation is deferred until the run has confirmed work, right after the Phase 1 decision when the apply set is non-empty or the security plan has a resolution to apply, before anything is installed, or before Phase 5b on a refresh-only run (see Branch creation). Creating a worktree when there is nothing to update pollutes the branch list. Read the main checkout's root once with `git rev-parse --show-toplevel` and carry it as the literal `<main checkout path>`. Before discovery, check for an update worktree a run left behind:

   git worktree list --porcelain

When any record holds a `refs/heads/deps/` branch, or a `refs/heads/worktree-deps+` branch (a run interrupted between creating the worktree and renaming its branch), stop before discovery and create nothing. Report its path and branch with two next steps: re-run `/update-deps` inside it, which continues there; or remove it with the removal commands in the worktree notice (`references/worktree.md`, `## The worktree notice`).

Then, still before discovery, run the pull gate:

   . .gaia/scripts/main-only-lib.sh
   gaia_pull_gate "/update-deps"

On a non-zero exit, read `.claude/skills/update-gaia/references/pull-gate.md` and follow it with `/update-deps`, this run's original arguments and the exit code, before anything below creates a branch, worktree, claim or SPEC id.

Package layout

The repository is a pnpm workspace with one lockfile at the root. App dependencies (everything the React app imports or builds with) are declared in `apps/web/package.json`; harness dependencies (lint-staged, prettier, `typescript` for the harness helpers) and the `gaia.updateDepsHold` map are in the root `package.json`. `overrides:` and `minimumReleaseAge` stay in the root `pnpm-workspace.yaml`. Add or bump an app dependency with `pnpm -C apps/web add <pkg>@<spec>`, a harness dependency with `pnpm add -w <pkg>@<spec>` from the root. The quality gate runs the root `pnpm typecheck`, `pnpm lint` and `pnpm test:ci` across every workspace member, and `pnpm pw` and `pnpm build`, which proxy to `apps/web`.

Flags and run modes

Parse the arguments before any other work. `--security` together with `--scope` refuses at once, before discovery, printing `/update-deps: --security and --scope cannot be combined; pass o