Skip to content

j-mauro-r/SAT-Dengue-V2 / .agents/skills/deepworkplan/addons/dependency-upgrade

deepworkplan-addon-dependency-upgrade

Verified

DeepWorkPlan addon that safely upgrades a repo's dependencies — reasoning about the repo's ACTUAL package manager (npm/pnpm/yarn + ncu, pip/poetry/uv, cargo, go mod, bundler, composer, and more) rather than assuming npm — with a batched, validated, revertible workflow that detects the manager and manifests/lockfiles, classifies upgrades (patch/minor/major), upgrades in safe batches, runs the repo's real validation gate after each batch, reverts a failing batch, and summarizes. Near-default — offered for every repo with declared dependencies, and its delegator installs under the onboarding consent unless declined; upgrades themselves never run automatically, only as explicit, gated work. Never required for baseline conformance; reconciles with the repo's existing tooling. Use when the developer wants to bring dependencies up to date without breaking the build.

FileKindSize
SKILL.mdskill md10.4 KB
SPEC.mdmarkdown8.5 KB
addon.jsonconfig221 B
templates/ecosystems.mdmarkdown5.8 KB
templates/lib-upgrade-command.mdmarkdown2.0 KB
templates/upgrade-report.mdmarkdown1.4 KB
# SPEC.md — Dependency-Upgrade Addon (Normative)

## Abstract

This document is the **normative specification** of the DeepWorkPlan
**dependency-upgrade addon**: a **near-default** capability — offered for every
repo with declared dependencies, its delegator installed under the onboarding
consent unless explicitly declined — that **safely upgrades a
repository's dependencies** with a **batched, validated, revertible** workflow.
It defines **package-manager detection** (RFC-2119), **semver classification**,
the **batched-upgrade** rule, the **validate-after-each-batch** gate, the
**revert-on-failure** rule, the **reconcile-don't-clobber** behavior, and the
**validation** step.

The addon is **package-manager agnostic**: it reasons about the repo's **actual**
manager (npm/pnpm/yarn, pip/poetry/uv/pipenv, cargo, go mod, bundler, composer,
and more) rather than assuming npm. It is governed by `../README.md` and
`../../spec/ADDONS.md`: it is **never** required for baseline AI-first
conformance.

## Status of This Document

| Field | Value |
|-------|-------|
| **Version** | 2.1.0 |
| **Status** | Stable |
| **Companions** | `SKILL.md`, `templates/ecosystems.md`, `templates/upgrade-report.md`, `templates/lib-upgrade-command.md`, `../README.md`, `../../spec/ADDONS.md` |
| **License** | MIT |

## 1. Conventions

The RFC 2119 keywords (**MUST**, **MUST NOT**, **SHOULD**, **SHOULD NOT**,
**MAY**, **OPTIONAL**) are interpreted as in
[RFC 2119](https://www.rfc-editor.org/rfc/rfc2119).

Throughout, a **batch** is a small, coherent set of dependency upgrades applied
and validated together, and the **gate** is the repo's real validation command
set (lint + typecheck + build + test, as applicable).

---

## 2. Package-Manager Detection (the part the addon reasons about)

- The addon **MUST** detect the package manager(s) from the **manifest and
  lockfile that actually exist** in the repo. It **MUST NOT** assume npm or any
  single ecosystem.
- Detection signals **MUST** be derived from real files, e.g.:

  | Ecosystem | Manifest | Lockfile → manager |
  |-----------|----------|--------------------|
  | JS / TS | `package.json` | `pnpm-lock.yaml` → pnpm · `yarn.lock` → yarn · `package-lock.json` → npm |
  | Python | `pyproject.toml` / `requirements*.txt` / `Pipfile` | `poetry.lock` → poetry · `uv.lock` → uv · `Pipfile.lock` → pipenv · pinned `requirements*.txt` → pip / pip-tools |
  | Rust | `Cargo.toml` | `Cargo.lock` → cargo |
  | Go | `go.mod` | `go.sum` → go modules |
  | Ruby | `Gemfile` | `Gemfile.lock` → bundler |
  | PHP | `composer.json` | `composer.lock` → composer |

- A repo **MAY** contain **multiple** ecosystems (e.g. a JS frontend + a Python
  service). The addon **MUST** handle each ecosystem with its own manager and its
  own batches.
- For JS/TS, `ncu` (npm-check-updates) **MAY** be used as the cross-manager
  **version checker**, but the **install/update verb MUST** be the detected
  manager's (`pnpm install`, `yarn install`, `npm install`).
- The full per-ecosystem command reference is `templates/ecosystems.md`; it is a
  **checklist**, not an answer key — **detected reality wins**.

---

## 3. Semver Classification

- Every outdated dependency **MUST** be classified by semantic version against
  its current pinned version:
  - **patch** `X.Y.Z → X.Y.(Z+1)` (safest),
  - **minor** `X.Y.Z → X.(Y+1).0` (usually safe),
  - **major** `X.Y.Z → (X+1).0.0` (breaking changes possible).
- **patch + minor** upgrades **MAY** be batched automatically.
- **major** upgrades **MUST** require explicit developer approval before
  inclusion; the addon **MUST** present them and wait.
- Tightly coupled packages (a tool + its plugins; a framework + its companion
  packages) **SHOULD** be upgraded in the **same** batch so a peer-dependency
  constraint is not split across batches.

---

## 4. Batched Upgrade

- The addon **MUST** apply upgrades in **small, coherent batches** and **MUST
  NOT** upgrade everything at once (an all-at-once upgrade makes a failure
  impossible to isolate or revert cleanly).
- A reasonable order is: **patch** batch → **minor** batch → each approved
  **major** on its own.
- Each batch **MUST** use the detected manager for approved package versions
  only and keep manifest and lockfile consistent. Lockfile-only updates within
  existing constraints are valid. The addon **MUST NOT** hand-edit a lockfile.
- Before each batch, the addon **MUST** capture a recoverable snapshot of owned
  files (including absence) and the environment. Dependency scripts/build hooks
  require explicit authorization; suppress them with supported manager controls
  or stop before executing them. A general upgrade request does not waive this.

---

## 5. Validate-After-Each-Batch Gate

- After every batch, the addon **MUST** run the **repo's real validation gate** —
  the actual lint / typecheck / build / test commands the repo uses.
- The gate **MUST** be discovered from the repo (`AGENTS.md` Quick Commands,
  `docs/DEVELOPMENT_COMMANDS.md`, the manifest's scripts, or the devcontainer
  addon's `codecheck`/`check`/`fix`/`test` aliases if present). The addon **MUST
  NOT** invent a gate.
- A batch is **accepted** only if the gate passes. A batch whose gate fails
  **MUST** be handled per §6.

---

## 6. Revert on Failure

- If a batch's gate fails, the addon **MUST** revert **just that batch**:
  restore the exact pre-batch snapshot, preserving earlier successful batches
  and pre-existing changes; re-sync the environment without advancing resolution
  or enabling unapproved scripts, and confirm the previous gate again. Restore
  from `HEAD` is valid only when proven identical to that snapshot. Failed
  restoration or validation **MUST** block further batches.
- The addon **MUST** record the reverted batch as skipped/failed with the failing
  gate and reason. It **MAY** retry the batch one package at a time to isolate the
  culprit.
- A failing major upgrade **MUST** be set aside, never force-installed past a
  broken gate.
- The addon **MUST NOT** auto-commit; it surfaces the diff and lets the developer
  commit (suggested: `chore(deps): …`).

---

## 7. Reconcile, Don't Clobber

- The addon operates on the repo's **existing** manifests and lockfiles; it
  **MUST** preserve every pin and constraint it does not deliberately upgrade.
- It **MUST NOT** delete or rewrite a lockfile wholesale, change the package
  manager, or remove dependencies without explicit approval.
- It **MUST** record what it changed (in the upgrade report).

---

## 8. Onboarding Hook + `/lib-upgrade` Delegator

- The addon's onboarding hook (`SKILL.md`) is offered by `onboard` Phase 7b for
  **every repo with declared dependencies** (a manifest or lockfile). Under the
  onboarding consent the delegator below installs **unless the developer
  explicitly declines**; a prior explicit acceptance is never re-asked, and a
  decline leaves a baseline-conformant repo with no command.
- The addon **MUST NOT** run any upgrade at install time. Installing the
  delegator only adds the `/lib-upgrade` command into the target repo's
  `.agents/commands/` (template: `templates/lib-upgrade-command.md`) delegating
  to this addon; an upgrade itself is always explicit, gated work (a plan task
  with validation gates, or a direct invocation).

---

## 9. Validation Step (run after applying)

The addon is correctly applied when **all** hold:

1. The package manager(s) were **detected from real manifests/lockfiles**, not
   assumed (no npm/ncu run in a non-JS repo).
2. Upgrades were **classified** by semver and **batched** (never all-at-once);
   majors required explicit approval.
3. The **repo's real gate** ran after **each** batch and every accepted batch
   passes it.
4. Any failing batch was **reverted** (manifest + lockfile restored, install
   resynced, gate green) and recorded.
5. No lockfile was hand-edited; no auto-commit happened.
6. An upgrade **report** (`templates/upgrade-report.md`) summarizes upgraded /
   skipped / reverted / validated.
7. If accepted via onboarding, a `/lib-upgrade` delegator exists in the repo's
   `.agents/commands/`; if declined, none was installed.

---

## 10. References

- [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119)
- `SKILL.md` (the onboarding hook + flow), `templates/*` (reasoning aids)
- `../README.md` (addon mechanism), `../../spec/ADDONS.md` (concept + pointer)
- [Semantic Versioning](https://semver.org/)
- [npm-check-updates](https://github.com/raineorshine/npm-check-updates)

---

*Part of the DeepWorkPlan methodology v5.0.0, MIT License, by [Dailybot](https://dailybot.com) / dailybotops.*
add-product-e2e-evalpaperclipai/paperclipAdd or extend a Paperclip full-stack runner E2E workflow, fixture, matcher, or report evidence path for local or Daytona execution.Stars: 115kUpdated Claude CodeCodexVerifiedInstall
add-runner-evalpaperclipai/paperclipAdd or extend a Paperclip Runner protocol evaluation definition, roster, assertion, or report fixture with provenance and narrow validation.Stars: 115kUpdated Claude CodeCodexVerifiedInstall
diagnose-why-work-stoppedpaperclipai/paperclipCompatibility entry point for failed, stalled, looping, or over-recovered Paperclip work. Use fix-failed-paperclip-run for the full diagnosis, regression, repair, real verification, and green-PR workflow; honor an explicitly requested diagnosis-only scope.Stars: 115kUpdated Claude CodeCodexVerifiedInstall
fix-failed-paperclip-runpaperclipai/paperclipDiagnose and fix failed, stuck, slow, or incorrectly blocked Paperclip tasks and runs. Use with a task/run URL or failure report to trace the root cause, prove a regression red then green, check second-order effects, verify the real workflow, and deliver a PR with passing checks.Stars: 115kUpdated Claude CodeCodexVerifiedInstall