repo-hygiene — Repository Health Check

pre-release

When to Use

• Onboarding to a new (or forgotten) repo — "what shape is this in?"
• Weekly/monthly maintenance sweep
• After a large refactor or dependency upgrade
• Before starting a new feature sprint
• When CI starts failing mysteriously
• After a team member leaves and you inherit their repo

Supported Stacks

package.json

package-lock.json

pyproject.toml

requirements.txt

go.mod

The Workflow

Step 0: Detect Project

# What are we working with?
ls package.json pyproject.toml go.mod 2>/dev/null
git rev-parse --show-toplevel

Step 1: Dependency Health

Node.js / npm

npm audit --json

npm outdated --json

npx depcheck --json

npx depcheck --json

missing

npm ls --all --json 2>/dev/null | grep -c '"deduped"'

# package.json changed more recently than lockfile?
LOCK_DATE=$(git log -1 --format=%ct -- package-lock.json 2>/dev/null || echo 0)
PKG_DATE=$(git log -1 --format=%ct -- package.json 2>/dev/null || echo 0)
if [ "$PKG_DATE" -gt "$LOCK_DATE" ]; then
  echo "⚠️ package.json modified after lockfile — run npm install"
fi

• D1:

  npm audit fix

  for compatible fixes;

  npm audit fix --force

  for breaking (review changes). For stubborn advisories: check if the vuln is reachable, or override in

  package.json

  overrides

  .
• D2:

  npm update

  for minor/patch;

  npm install <pkg>@latest

  for major (check changelogs).
• D3:

  npm uninstall <pkg>

  for each unused dep.
• D4:

  npm install <pkg>

  for each missing dep.
• D5:

  npm install

  to regenerate lockfile, commit it.
• D6:

  npm dedupe

  then verify tests pass.

Python (uv / pip)

pip-audit --format=json

uv pip list --outdated

pip list --outdated --format=json

deptry . --json

uv.lock

pyproject.toml

• D1:

  uv pip install --upgrade <pkg>

  for each vulnerable package. Check advisories for minimum safe version.
• D2:

  uv pip install --upgrade <pkg>

  per package, or

  uv lock --upgrade

  for all.
• D3: Remove from

  [project.dependencies]

  in

  pyproject.toml

  , then

  uv sync

  .
• D5:

  uv lock && uv sync

  .

Go

govulncheck ./...

go list -m -u all

go mod tidy -v

• D1:

  go get <module>@latest

  for vulnerable deps, then

  go mod tidy

  .
• D2:

  go get -u ./...

  for all, or

  go get <module>@latest

  selectively.
• D3:

  go mod tidy

  removes unused; commit

  go.mod

  and

  go.sum

  .

Step 2: Git Hygiene

git branch --merged main | grep -v '^\*|main|develop'

git branch -r --merged origin/main | grep -v 'HEAD|main|develop'

.gitignore

git status --porcelain | grep '^??'

git status --porcelain

# Top 10 largest tracked files
git ls-files -z | xargs -0 -I{} git log --diff-filter=A --format='%H' -1 -- '{}' | head -20
# Simpler: just check current tree
git ls-files -z | xargs -0 du -sh 2>/dev/null | sort -rh | head -10

• Universal:

  .env

  ,

  .env.*

  ,

  *.local

  ,

  .DS_Store

  ,

  Thumbs.db

  ,

  *.swp

  ,

  .idea/

  ,

  .vscode/

  (or be deliberate about tracking it)
• Node:

  node_modules/

  ,

  dist/

  ,

  build/

  ,

  coverage/

  ,

  .turbo/

  ,

  .next/

• Python:

  __pycache__/

  ,

  *.pyc

  ,

  .venv/

  ,

  venv/

  ,

  .mypy_cache/

  ,

  .pytest_cache/

  ,

  *.egg-info/

• Go: binary name (check

  go build -o

  ),

  vendor/

  (if not vendoring)

• G1:

  git branch -d <branch>

  for each merged local branch.
• G2:

  git push origin --delete <branch>

  for each merged remote branch. Be careful — confirm with team.
• G3: For files that shouldn't be tracked: add to

  .gitignore

  ,

  git rm --cached <file>

  . For files already in history:

  git filter-repo

  or BFG Repo-Cleaner (destructive — confirm first).
• G4: Add missing patterns to

  .gitignore

  . Use a generator like gitignore.io as a starting point.
• G5: Either add to

  .gitignore

  or

  git add

  if they should be tracked.

Step 3: CI/CD Health

ls .github/workflows/*.yml 2>/dev/null

grep -rE 'uses: [^@]+@v[0-9]' .github/workflows/

permissions:

write-all

echo ${{ secrets.* }}

$GITHUB_OUTPUT

$GITHUB_ENV

actions/create-release@v1

set-output

::set-env

engines

.nvmrc

pyproject.toml [requires-python]

• C2: Replace

  uses: actions/checkout@v4

  with

  uses: actions/checkout@<full-sha>

  . Find SHA:

  gh api repos/actions/checkout/git/ref/tags/v4 --jq .object.sha

  or check the releases page.
• C3: Add explicit

  permissions:

  at job level. Start with

  contents: read

  and add only what's needed.
• C4: Remove secret interpolation. Use

  environment:

  blocks or write to files with masking.
• C5: Replace deprecated actions with current equivalents.

  set-output

  →

  $GITHUB_OUTPUT

  file.
• C6: Align versions. Use

  .nvmrc

  or

  engines

  as the source of truth.

Step 4: Code Quality Drift

git grep -ciE '(TODO|FIXME|HACK)' -- '*.ts' '*.js' '*.py' '*.go' ':!node_modules' ':!vendor' ':!.venv'

console.log

git grep -c 'console\.log' -- 'src/**/*.ts' 'src/**/*.js' ':!*.test.*' ':!*.spec.*'

git grep -cE '(it\.skip|test\.skip|describe\.skip|xit|xdescribe|@pytest\.mark\.skip|t\.Skip)' -- '*.test.*' '*.spec.*' '*_test.*' '*_test.go'

npm run lint

ruff check .

golangci-lint run

npm test

pytest

go test ./...

npm run build

uv build

go build ./...

npx tsc --noEmit

npx ts-prune 2>/dev/null | grep -v '(used in module)'

• Q1: Triage each TODO — either do it, create an issue/task for it, or remove it if obsolete.
• Q2: Replace with a proper logger, or remove debug logging.

  grep -rn 'console.log' src/

  to find them.
• Q3: Either fix the underlying issue and un-skip, or delete the test if the feature was removed.
• Q4–Q7: Fix the errors. Run the tool, address each issue.
• Q8: Remove unused exports, or add

  // ts-prune-ignore-next

  if they're part of the public API.

Step 5: Documentation Freshness

git log -1 --format=%cr -- README.md

git log -1 --format=%cr -- src/

package.json

license

pyproject.toml

license

.pi/AGENTS.md

# Find markdown links and verify targets exist
grep -roE '\[([^]]+)\]\(([^)]+)\)' *.md docs/**/*.md 2>/dev/null | \
  grep -v 'http' | \
  while IFS= read -r line; do
    # Extract path from markdown link
    path=$(echo "$line" | sed 's/.*](\([^)]*\)).*/\1/' | sed 's/#.*//')
    if [ -n "$path" ] && [ ! -e "$path" ]; then
      echo "BROKEN: $line"
    fi
  done

• F1: Write a README with: what it does, how to install, how to use, prerequisites, license.
• F2: Review README against current code — update examples, API docs, feature lists.
• F3: Add a CHANGELOG.md. Consider

  @changesets/cli

  for automated generation (see

  pre-release

  skill).
• F4: Update or remove broken links.
• F5: Add a LICENSE file. Use choosealicense.com if unsure.
• F6: Make LICENSE file and metadata agree.
• F7: Update AGENTS.md to reflect current project structure.

Step 6: Configuration Consistency

.editorconfig

tsconfig.json

"strict": true

.prettierrc

ruff.toml

gofmt

.eslintrc*

eslint.config.*

ruff.toml

golangci-lint

package.json

engines

pyproject.toml

requires-python

.nvmrc

.python-version

engines

requires-python

• X1: Add

  .editorconfig

  . Minimal:

  root = true

  ,

  [*]

  block with

  indent_style

  ,

  indent_size

  ,

  end_of_line

  ,

  insert_final_newline

  .
• X2: Set

  "strict": true

  in

  tsconfig.json

  . Fix resulting type errors (usually worth it).
• X3–X4: Add config files. Use the project's existing style as a baseline.
• X5–X6: Pick one source of truth (recommend

  engines

  /

  requires-python

  ) and align everything else.

Step 7: Security Posture

pre-release

.env

.local

git ls-files '*.env' '*.env.*' '*.local' '*.local.*' '.env' '.env.local'

.env.example

.env

.gitignore

git grep -iE '(api[_-]?key|secret|password|token)\s*[:=]\s*["\x27][^"\x27]{8,}' -- ':!*.lock' ':!node_modules' ':!*.example' ':!*.sample'

.gitleaks.toml

chmod 777

0777

• S1:

  git rm --cached <file>

  , add to

  .gitignore

  , commit. If the file contained real secrets, rotate them immediately — they're in git history.
• S2: Create

  .env.example

  with placeholder values (

  <REPLACE_ME>

  ) for every var in

  .env

  .
• S3: Move secrets to env vars or a secrets manager. Replace in code with

  process.env.VAR

  /

  os.environ["VAR"]

  .
• S4: Add

  .gitleaks.toml

  (even a minimal one enables CI scanning). Or add

  gitleaks

  to pre-commit hooks.
• S5: Use least-privilege permissions (

  644

  for files,

  755

  for executables).

Step 8: Project Metadata

name

version

description

license

package.json

pyproject.toml

repository

keywords

FUNDING.yml

.github/FUNDING.yml

pi-package

pi

files

• M1–M3: Add the missing fields to

  package.json

  or

  pyproject.toml

  .
• M4: Create

  .github/FUNDING.yml

  with

  github: <username>

  .
• M5: See pi package docs for required fields.

Baseline Tracking

.pi/hygiene-baseline.json

{
  "timestamp": "2026-02-14T23:00:00Z",
  "stack": ["node"],
  "scores": {
    "dependencies": { "status": "healthy", "vulns": 0, "outdated": 3, "unused": 0 },
    "git": { "status": "healthy", "stale_branches": 0, "large_files": 0 },
    "ci": { "status": "warning", "unpinned_actions": 2, "permission_issues": 0 },
    "quality": { "status": "healthy", "todos": 5, "skipped_tests": 0, "lint_clean": true },
    "docs": { "status": "warning", "readme_stale_days": 45, "broken_links": 1 },
    "config": { "status": "healthy", "strict_ts": true, "formatter": true, "linter": true },
    "security": { "status": "healthy", "tracked_env": 0, "hardcoded_secrets": 0 },
    "metadata": { "status": "healthy", "complete": true }
  },
  "overall": "7/10"
}

📉 Dependencies: 0 → 3 vulnerabilities (regression since last check)
📈 Quality: 15 → 5 TODOs (improvement!)
→  CI: unchanged — 2 unpinned actions remain

Report Format

# Repo Health: <project-name>
## Score: 7/10 — GOOD
## Stack: Node.js + TypeScript
## Last check: 2026-01-15 (30 days ago) | Baseline: 6/10 📈

### 🔴 Fix Now (2)
| # | Category | Issue | Fix |
|---|----------|-------|-----|
| S1 | Security | `.env.local` tracked in git | `git rm --cached .env.local` |
| D1 | Deps | 2 high-severity npm audit findings | `npm audit fix` |

### 🟡 Fix Soon (4)
| # | Category | Issue | Fix |
|---|----------|-------|-----|
| D2 | Deps | 8 outdated packages (2 major) | `npm outdated` → upgrade |
| C2 | CI | 3 actions not pinned by SHA | Pin to commit SHA |
| F2 | Docs | README 45 days behind source | Review and update |
| Q3 | Quality | 2 skipped tests | Fix or remove |

### 🟢 Healthy (12)
- ✅ Dependencies: no unused, no phantom, lockfile fresh
- ✅ Git: clean tree, no stale branches, no large files
- ✅ Code: lint clean, build passes, tests pass, strict TS
- ✅ Config: EditorConfig, Prettier, ESLint all configured
- ✅ Security: no tracked secrets, .env.example present
- ✅ Metadata: all fields present, license matches

### 📊 Trends (vs. baseline 2026-01-15)
| Category | Then | Now | Trend |
|----------|------|-----|-------|
| Vulnerabilities | 0 | 2 | 📉 |
| Outdated deps | 5 | 8 | 📉 |
| TODOs | 15 | 8 | 📈 |
| Skipped tests | 0 | 2 | 📉 |

### Recommendations
1. **Immediate**: Fix the 2 security/vulnerability items above
2. **This week**: Pin CI actions and update stale README
3. **Ongoing**: Address skipped tests and outdated deps in next sprint

Use your project's task tracking to schedule these items.

Scoring

Auto-Fix Offers

Safe to offer (low risk, reversible)

• Delete merged local branches (

  git branch -d

  )
• Run

  npm audit fix

  (compatible fixes only, not

  --force

  )
• Run

  npm dedupe

  /

  go mod tidy

• Add missing

  .gitignore

  patterns
• Add

  .editorconfig

  from template
• Remove

  console.log

  from source files
• Create

  .env.example

  from

  .env

  (with values replaced by

  <REPLACE_ME>

  )
• Add missing

  package.json

  fields (description, repository, keywords)
• Create

  .github/FUNDING.yml

Offer with warning (confirm carefully)

• Delete merged remote branches (

  git push origin --delete

  )
• Run

  npm audit fix --force

  (may have breaking changes)
• Major dependency upgrades
• Enable TypeScript strict mode (may produce many errors)
• Update CI action pinning (must verify correct SHAs)

Never auto-fix (explain, let user decide)

• Removing tracked

  .env

  files (may need secret rotation)
• Rewriting git history (BFG / filter-repo)
• Changing license files
• Modifying CI permissions model
• Removing hardcoded secrets (need to determine replacement strategy)

Tips

• Run early, run often. A monthly cadence catches drift before it compounds.
• Don't try to fix everything at once. Focus on 🔴 items first, batch 🟡 items into a maintenance sprint.
• Baseline tracking is your friend. Even if the score isn't perfect, trending upward means you're winning.
• Pair with pre-release. Run

  repo-hygiene

  for ongoing health,

  pre-release

  when you're ready to ship. They complement each other — hygiene keeps the baseline high so pre-release has fewer surprises.
• New repos start clean. Run this right after

  git init

  to establish a perfect baseline. It's easier to maintain 10/10 than to recover from 4/10.