kortix-ai Proactive and schedule-driven; covers all outdated deps — patch, minor, and major — with full verification and explicit breaking-change handling.
Step 0 — Orient and resume
# Read the durable ledger first — last-run state, open PRs, known broken
# upgrades, and pinned packages to skip.
cat .kortix/memory/dependency-upgrade-log.md 2>/dev/null || echo "(no ledger yet)"
# Check any open upgrade PRs from a prior run.
gh pr list --repo {{target_repo}} --state open \
--search 'in:title "chore(deps)" OR label:dependencies' \
--json number,title,headRefName,statusCheckRollup,url
If an open PR from a prior run is still on CI or in review, note it and don't duplicate the work. Drive a stalled-but-fixable PR to green; otherwise leave it for review and move on.
Step 1 — Freshen the repo
# Warm clone at /workspace/repo if present; else clone fresh (blobless).
if [ -d /workspace/repo/.git ]; then
cd /workspace/repo && git fetch origin && git checkout main && git reset --hard origin/main
else
git clone --filter=blob:none https://github.com/{{target_repo}}.git /workspace/repo
cd /workspace/repo
fi
# Install so the toolchain can resolve versions.
pnpm install --frozen-lockfile 2>&1 | tail -20
Never start an upgrade on a stale base. Adapt the package manager (pnpm /
npm / bun / pip / cargo…) to the project's toolchain.
Step 2 — Discover what is outdated
cd /workspace/repo
pnpm outdated --recursive --json 2>/dev/null || pnpm outdated --recursive
pnpm audit --json 2>/dev/null | jq '.advisories | length' || true
Parse into three tiers:
| Tier | Criteria | Default action |
|---|---|---|
| patch | x.y.Z only |
Apply + verify; group into one PR |
| minor | x.Y.z |
Apply + verify; group by area or fold into the patch PR |
| major | X.y.z |
Apply per package; verify with breaking-change analysis; own PR (or small cohesive group) |
Skip anything in the ledger's pinned-packages section.
Step 3 — Isolated upgrade branch
cd /workspace/repo
BRANCH="upgrade/deps-$(date +%Y-W%V)"
git checkout -b "$BRANCH" origin/main # or check out an existing branch from this week
One branch per weekly run.
Step 4 — Apply the upgrades
Patch + minor batch — apply together:
cd /workspace/repo
npx taze minor --recursive --write 2>&1 | tee /tmp/taze-minor.log
pnpm install 2>&1 | tee /tmp/install-minor.log
Major upgrades — one at a time:
- Read the changelog / GitHub releases for the package.
- Grep the codebase for renamed/removed APIs.
- Apply the bump + required migration in the same commit.
- Run the suite (Step 5) before the next major. If it fails and the fix is
~30 lines of non-trivial code, revert this major, file a tracked issue, and continue with the rest.
Step 5 — Full verification suite (the gate)
The upgrade is not ready until every check is green.
cd /workspace/repo
pnpm install 2>&1 | tee /tmp/up-install.log
pnpm typecheck 2>&1 | tee /tmp/up-typecheck.log
pnpm lint 2>&1 | tee /tmp/up-lint.log
pnpm build 2>&1 | tee /tmp/up-build.log
pnpm test 2>&1 | tee /tmp/up-unit.log
pnpm test:integration 2>&1 | tee /tmp/up-integration.log # if < ~10 min
pnpm audit --prod 2>&1 | tee /tmp/up-audit.log
Interpreting failures:
| Failure | Action |
|---|---|
| Type error from an upgraded package's types | Apply the migration (fix inline if 2–3 lines); else revert + file an issue |
| Test failure testing the upgraded package | If behavior legitimately changed, update the test; if it's a regression, revert + file |
| Test failure in an UNRELATED test | File a bug (likely pre-existing flake); don't revert unless you can prove causation |
| Build failure | Fix the import/config; if > 3 non-mechanical files, split the major into its own PR |
| Audit finds a NEW vuln from the upgrade | Revert + file. Never trade a clean audit for a dirty one |
Step 6 — Commit
cd /workspace/repo
git add '**/package.json' pnpm-lock.yaml
git add -p # review any migration source changes before staging
git commit -m "chore(deps): upgrade dependencies $(date +%Y-W%V)
Verification: typecheck ✓ lint ✓ build ✓ unit ✓ integration ✓ audit ✓"
Step 7 — Open the PR (only when Step 5 is fully green)
A partial green (checks skipped/timed out) is NOT acceptable — rerun or debug.
cd /workspace/repo
git push origin "$BRANCH"
gh pr create --repo {{target_repo}} --base main --head "$BRANCH" \
--title "chore(deps): upgrade dependencies $(date +%Y-W%V)" \
--label dependencies \
--body "Generated by the dependency upgrade agent. The full suite passed in the
sandbox before this PR was opened. Verification: install/typecheck/lint/build/
unit/integration/audit all ✓. A human owns the merge."
Step 8 — Update the ledger
Append a dated entry to .kortix/memory/dependency-upgrade-log.md (see
<ledger-format>), then open + self-merge a scoped change request for the ledger
update only.