tag-audit

Tag Audit

Detects tag/version misalignment that causes E409 conflicts, failed releases, and deploy version drift. Works for both npm package releases and app deploys.

When to Use

• Before any release (/release-maintenance or /project-release)
• After a failed Release workflow (E409 Conflict)
• After a failed deploy (version mismatch)
• When package.json version doesn't match latest tag
• Periodic health check on version state

Step 0: Detect Release Type

# Check if this is an npm package or an app
if grep -q '"publishConfig"' package.json 2>/dev/null || grep -q 'npm.pkg.github.com' package.json 2>/dev/null; then
  echo "TYPE: npm-package"
else
  echo "TYPE: app-deploy"
fi

# Check if semantic-release is configured
if [ -f ".releaserc.json" ] || [ -f ".releaserc.js" ] || grep -q 'semantic-release' package.json 2>/dev/null; then
  echo "RELEASE: semantic-release (tags are authoritative)"
else
  echo "RELEASE: manual (package.json + tag must match)"
fi

Audit Procedure

Step 1: Gather State (run in parallel)

# Current package.json version
grep '"version"' package.json | head -1

# Local tags
git tag -l 'v*' | sort -V | tail -10

# Remote tags
git ls-remote --tags origin | grep -E 'refs/tags/v[0-9]' | sort -t '/' -k 3 -V | tail -10

# npm published version (npm packages only)
npm view $(grep '"name"' package.json | head -1 | sed 's/.*": *"//;s/".*//' ) version --registry https://npm.pkg.github.com 2>/dev/null || echo "NOT PUBLISHED or APP"

# Check if local tags match remote
git fetch --tags --dry-run origin 2>&1

# For app deploys: check deployed version if available
# Railway: railway status
# Vercel: vercel ls --limit 1

Step 2: Alignment Check

Build a comparison table:

For npm packages:

Source	Version	Status
package.json	X.Y.Z	-
Latest local tag	vX.Y.Z	match/mismatch
Latest remote tag	vX.Y.Z	match/mismatch
npm registry	X.Y.Z	match/mismatch