Menu
Delta-driven dependency upgrades — a script gathers the evidence, you read the artifact and judge. Use when the user asks to upgrade, bump, or CVE-audit dependencies.
Instalar com Codex ou Claude Copie este prompt, cole no Codex, Claude ou outro assistente e deixe que ele revise a página da skill e instale para você.
Baseado na classificação ocupacional SOC
| name | upgrade-packages |
| description | Delta-driven dependency upgrades — a script gathers the evidence, you read the artifact and judge. Use when the user asks to upgrade, bump, or CVE-audit dependencies. |
A script gathers every release delta, GHSA advisory, and codebase-usage site into one JSON artifact; you read it and judge. Never touch the registry, GitHub, or GHSA directly — every citation comes from the artifact (diffUrl, changelogUrl, advisory url), so no model priors sneak in. Sources of truth: the artifact, then the codebase. Cite where you read every claim.
This repo uses bun with exact pins in package.json — bun update alone bumps nothing. Lift an exact pin with bun update <pkg>@<target> (or bun update <pkg> --latest per package) / a package.json edit. Never bun update --latest across the board. The check-updates script is inventory-only.
Run bun run upgrade-packages:evidence (defaults to --out scripts/upgrade-packages/artifact.json; pass --out <path> to override). Requires network access — the script calls gh api (GitHub releases + GHSA advisories) and bun pm view; a sandboxed network allowlist that blocks api.github.com will make every gh call fail (the artifact degrades to error markers with changelogUrl deep-dive links). Release/advisory data is cached to scripts/upgrade-packages/.cache/ (1h TTL) so re-runs are fast and don't re-trip rate limits. Read the artifact. Schema + how-to-read: REFERENCE.md.
Done when: the artifact exists and you've read inventory, outdated, audit, deltas, and usage.
For each outdated package, produce a cited verdict + band:
bumpClass (patch/minor/major/prerelease). Coupled deps: if a patch bump's peer/dep requires a minor+ bump of another direct dep (check deltas[<pkg>][].peerEngine + the other package's bumpClass), move the coupled set up a band.audit.ghsa verdict is priority-bump — goes first within its band.audit.ghsa verdict is check-failed (gh/parse/cache failure, id:"error") — inconclusive, not a vuln; re-run evidence or deep-dive the changelogUrl before treating as blocked.deltas[<pkg>][].error leaves the range uncovered and the missing version can't be sourced via its diffUrl, OR a breaking/security/peerEngine delta is a break-risk you can't resolve (see Phase 3).Cite the diffUrl/changelogUrl/advisory url for every verdict.
Done when: every outdated package has a cited verdict, a band, and a coupled-set tag; every priority-bump is flagged for Phase 3.
For every break-risk delta (breaking, deprecations, peerEngine, or a behavior-changing fix in security/features — e.g. callback debounce, CVE patch altering semantics), cross-check usage[<pkg>]. Use callSites (codemap) for blast radius — where the symbol is actually called, not just imported; importedSymbols + typeOnlySymbols for what's in scope; sites for import locations. Classify: no usage / code-aligned / breaks (needs a code change first). Cite callSites/sites (file:line). A breaks with no code change → the bump is blocked or deferred.
Done when: every break-risk delta has a citation-backed no usage | aligned | breaks verdict; every breaks has a proposed code change.
Bands: patch → minor → major, verify after each per verify-after-each-step. Within each band, priority-bump packages first; coupled sets move up together; prereleases go in the patch band (moving-target, same-major-line gate).
bun update <pkg>@<target> per package); run the CI mirror (below).breaks code change first, bump, then checks. Defer unresolved majors (cited reason) unless they clear a high/critical advisory.A bumped parser/resolver/CSS package can change extraction output — re-run bun run test:golden and regenerate any affected goldens. Re-run bun audit after each band — a new advisory → revert that bump and re-research. Commit per band only when the user asked to commit.
Done when: CI mirror (bun run check + bun run build) green for patch + minor; every major green-and-committed/staged or deferred with a cited reason; no breaks unaddressed; final bun audit clean or every remaining advisory documented.
Run what .github/workflows/ci.yml runs — ci.yml is the SSOT:
bun run check → build + format:check + lint:ci + test + test:scripts + typecheck + test:golden + test:agent-eval (5 of 6 CI jobs: Format, Lint, Typecheck, Test, Build)bun run build → covered by check, but re-run explicitly if a bump only touched build tooling (tsdown/oxc) — do not skip; dep upgrades break the bundler/codegen far more often than typesbun audit → CI's audit job blocks on high/critical (it greps bun audit output for high: / critical:); treat any high/critical advisory as blocking-with-triage, lower severities as documentedProduce: security (advisories → verdict, with GHSA id + URL + fixed-in), consolidated changeset (rolled up from deltas — per package current → target, bucketed breaking/deprecations/features/fixes/peer-engine, one line per delta), adoption opportunities (top ~5 features deltas the codebase isn't using — usage verdict + file:line + one-line why-adopt + follow-up; non-blocking), bumped packages (band → version → why-safe), deferred/blocked (cited reason + file:line), verification results. Every citation from the artifact. If the user asked to commit/PR, hand off to harden-pr full mode.
Done when: report accounts for every non-no-op package and advisory; every citation is real — no possibly, likely, or unstated assumptions.
bun update --latest across the board — per-package --latest/package.json edit for exact pins.bun audit as pass/fail — every advisory needs a cited verdict; a high/critical audit is blocking-with-triage.bun run build — bundler/codegen breakage beats type breakage for dep upgrades.REFERENCE.md — evidence artifact schema + how to read itverify-after-each-step — per-band checksharden-pr — full mode before PRVoice, tone, and format for the public Codemap docs (`apps/docs`, built with Blume). Use when authoring or editing apps/docs prose — landing, guides, concepts, recipes, reference, generated API — or deciding headline grammar, benefit framing, peer framing, or anti-pitch wording.
Repo-wide docs framework — what `docs/`, `docs/plans/`, `docs/research/`, `.agents/`, or any other doc-bearing surface in this repo looks like, what lifecycle each doc follows, and how to keep cross-references intact when slimming or moving content. Use when authoring or editing any `docs/**`, `docs/plans/**`, `docs/research/**`, `.agents/rules/**`, `.agents/skills/**`, or any new doc-bearing folder. Defines the lifecycle types (Reference / Roadmap / Plan / Audit / Research), the existence test every doc must pass, the closing-state lifecycles (delete + lift; never "Slim & keep in plans/"), the substrate variants (single `audit.md` vs `audits/<topic>.md`; conditional `glossary.md`), the surface tiers (repo-wide / per-tooling-area), and the cross-reference preservation discipline (grep before slim; preserve rule numbers cited from source). The Tier-2 priming layer at `.agents/rules/docs-governance.md` cites this skill and extends with codemap-specific bits only.
Bring a branch to pristine, maximum production readiness without changing PR intent — spawn parallel Task subagents (never inline review), fix in-bounds findings, loop autonomously until clean or pass cap, then report once. Use after a tracer-bullet commit (lite), before PR is done (full), on "harden", "harden-pr", "pristine", "review until clean", "production-ready pass", or "harden-pr reconcile". Invoking this skill authorizes one harden commit at cycle end. NEVER stop mid-loop to ask about commits, babysit, or the next pass. NEVER redesign the feature or change observable runtime behavior.
The product north-star — four Codemap tenets (structural over semantic, predicate-as-API, local-first / agent-native surfaces, honest scope). Use when making a design, API, or architecture decision, evaluating a trade-off, justifying a feature, or writing/reviewing a docs/plans entry.
Keep apps/docs in sync with merged product changes. On each run, audit recently merged PRs against docs content, update only drifted pages, regenerate API MDX when public exports/JSDoc drifted, verify with blume validate/check/build/audit, and open or update a docs/* PR — or report a clean no-op.
Full tier assignments, pairing conventions, and authoring checklist for .agents/ rules and skills. Use when creating or reviewing a rule or skill, deciding Tier 1 vs 2 vs 3, or auditing attachment cost.