[fedecor9]

What this is

A self-contained dependency- and toolchain-maintenance system for this repo,
built entirely as Claude Code configuration under .claude/ — no application
code changes. It's a dependency-manager agent orchestrating five skills
that each own one stage of a pipeline: audit what's outdated, prove an
update is actually safe before touching anything, apply it, keep the
pipeline's own docs in sync, and open a PR with the evidence as the
description.

It's built to be language/framework-agnostic: everything ecosystem-specific
(pub.dev URLs, OSV.dev's ecosystem name, Dart's version-suffix quirks) lives
in a small adapter file pair, not in the skills themselves. Adding a new
ecosystem later is one new .md + one new .json, no skill edited.

How it works

dependency-audit ─┐
                   ├─► dependency-update-audit ─► dependency-update-apply ─► dependency-doc-sync ─► dependency-update-pr
toolchain-audit  ──┘      (safety gate)              (apply the bump)         (fix stale docs)         (open the PR)
  (what's outdated?)   (prove it's safe)

1. dependency-audit — read-only inventory. Runs a script
   (scripts/fetch_updates.py) once per manifest that checks what's
   outdated, queries the registry and security advisories, and fetches the
   relevant changelog excerpt — then grades each finding on two independent
   axes: urgency (security-driven — why you'd want this) and risk
   (breaking-change-driven — what it costs). A critical CVE fixed by a
   trivial patch is urgency: critical, risk: none — those aren't the same
   question.
2. toolchain-audit — the same idea for the Flutter/Dart SDK, AGP,
   Kotlin, and the Gradle wrapper, kept separate since a toolchain bump's
   blast radius (native project files, CI config) is nothing like a package
   bump.
3. dependency-update-audit — the safety gate. Applies the candidate on
   a throwaway scratch branch, runs ./scripts/checks.sh for real, and only
   then writes a verdict — "the changelog looked fine" is never accepted
   as evidence. Also runs a batch check when a tier has multiple candidates,
   since packages that are each safe alone can still conflict when bumped
   together.
4. dependency-update-apply — applies whichever tier a human has
   explicitly approved, on its own branch, re-verifying for real before
   committing.
5. dependency-doc-sync — after a bump lands, fixes any of the
   pipeline's own docs that just went stale (e.g. a toolchain adapter's
   hardcoded "current version" note).
6. dependency-update-pr — opens one PR per safety tier (draft for
   anything with breaking changes), with the audit evidence as the PR body.

The agent never applies or opens a PR without an explicit human go-ahead per
tier — audit and safety-gate are the only stages that run unattended.

Example: input → output

Given this repo's real pubspec.yaml (flutter_secure_storage: ^10.3.1),
running dependency-audit produces (full worked example, including the
printed summary, in .claude/skills/dependency-audit/references/example-output.md):

{
  "package": "flutter_secure_storage",
  "current": "10.3.1",
  "upgradable": "10.3.4",
  "latest_compatible": "11.1.1",
  "bump": "major",
  "urgency": "maintenance",
  "risk": "medium",
  "tier": "review",
  "breaking_changes": [
    "11.0.0: items deprecated in v10 were removed; data saved with a deprecated algorithm becomes unusable unless the app already passed through v10 to migrate it.",
    "Android: removed KeyCipherAlgorithm.RSA_ECB_PKCS1Padding, StorageCipherAlgorithm.AES_CBC_PKCS7Padding, and the encryptedSharedPreferences/sharedPreferencesName AndroidOptions fields.",
    "Android: raised minSdk to 24 and compileSdk to 37."
  ]
}

which the skill renders as:

tier: review

package	current → target	urgency	risk	verdict
flutter_secure_storage	10.3.1 → 11.1.1	maintenance	medium	null (not yet audited)

10.3.4 is available with no manifest edit at all. 11.1.1 is available
if you're willing to take the breaking changes below — going from v10 to
v11 removes several deprecated Android cipher/options APIs, and the
changelog explicitly warns that skipping v10 on the way to v11 can make
previously-saved secure-storage data unreadable.

Note upgradable (10.3.4) vs latest_compatible (11.1.1) — the report
surfaces both a free, zero-risk bump and the further one that requires
accepting the breaking changes, rather than only showing whichever is
"furthest." Verified deterministic: two independent runs against the same
repo state produced byte-identical structured fields and near-identical
breaking_changes prose.

The scripts (why they exist)

Pushing deterministic work into small, stdlib-only Python scripts — rather
than having the agent hand-run and parse commands itself — fixes real bugs
found while testing this live: pub.dev's changelog is rendered HTML, not
markdown; pub outdated's output has quirks (a non-JSON banner prefix,
inconsistent fields); and free-form text edits to a manifest can silently
turn an exact pin into a range under pressure.

• dependency-audit/scripts/fetch_updates.py — one call per manifest
  replaces dozens of individual registry/advisory/changelog calls. Batches
  the security-advisory check (OSV.dev) into a single request instead of one
  per package.
• dependency-update-apply/scripts/bump_manifest.py — edits exactly one
  version number on one manifest line, preserving whatever pin style (exact
  or range) was already there. Refuses rather than guesses on any ambiguous
  match.
• dependency-update-apply/scripts/bump_toolchain_file.py — the same
  discipline for toolchain files, which span three incompatible formats
  (.fvmrc's JSON, settings.gradle's Groovy DSL, a version embedded in a
  URL) that no single parser handles — so this does a literal, disambiguated
  substitution instead.

Status

Built and tested this session: the audit path (read-only) has been run live
against this repo's real dependencies multiple times, including two parallel
clean-context trial runs confirming consistent output. The safety-gate →
apply → PR path has been validated on isolated synthetic candidates, not yet
run end-to-end against a real multi-package tier. Opening as a draft for
that reason.