Maintain — codebase maintenance pass

Run a structured codebase maintenance pass. This is a periodic health check — not a pre-commit review. Check each section, report findings, and fix what you can.

1. Dependency health

Detect the project's toolchain and audit dependencies:

Rust (if Cargo.toml exists):

cargo update --dry-run 2>&1 | head -30

Check for outdated or yanked crates. If cargo-audit is available:

cargo audit 2>/dev/null || echo "cargo-audit not installed — skip"

Node (if package.json exists):

npm outdated 2>/dev/null || echo "npm outdated not available"
npm audit --audit-level=moderate 2>/dev/null || echo "npm audit not available"

Python (if pyproject.toml or requirements.txt exists):

uv pip list --outdated 2>/dev/null || pip list --outdated 2>/dev/null || echo "skip"

Elixir (if mix.exs exists):

mix hex.outdated 2>/dev/null || echo "mix hex.outdated not available"
mix deps.audit 2>/dev/null || echo "mix deps.audit not available"

Report: list any dependencies with known vulnerabilities or major version bumps available.

2. Lint and format check

Run the full lint suite without fixing — report-only mode:

Rust:

cargo clippy -- -D warnings 2>&1
cargo fmt --check 2>&1

Node/TypeScript:

npx eslint . 2>/dev/null || npm run lint 2>/dev/null

Python:

ruff check . 2>/dev/null || uv run ruff check . 2>/dev/null

Go:

go vet ./... 2>/dev/null
gofmt -l . 2>/dev/null

Elixir:

mix format --check-formatted 2>&1
mix credo --strict 2>&1

Count warnings and errors. If any are found, fix them.

3. Test suite health

Run the full test suite and assess health:

Rust: cargo test 2>&1 Node: npm test 2>&1 Python: uv run pytest 2>/dev/null || pytest 2>/dev/null Go: go test ./... 2>/dev/null Elixir: mix test 2>&1

Report:

• Total tests, passed, failed, skipped
• Any flaky tests (if visible from output)
• Tests that are unusually slow

4. Dead code and stale patterns

Search the codebase for patterns that indicate maintenance debt:

TODO, FIXME, HACK, XXX, DEPRECATED

Also search for:

• #[allow(dead_code)] or #[allow(unused)] in Rust
• // eslint-disable or // @ts-ignore in TypeScript/JavaScript
• Unused imports (from lint output in step 2)
• Empty catch blocks or swallowed errors

For each finding, decide:

• Fix now if it's a quick cleanup (remove unused import, delete dead code)
• File a task if it requires more work: task add "<description>" project:<repo> +maintenance

5. Documentation freshness

Check that key documentation files exist and aren't stale:

• README.md — exists?
• CHANGELOG.md — has entries for recent work?
• CLAUDE.md — exists and reflects current project structure?

Read the first 20 lines of each to assess whether they're current. Flag any that reference features or structures that no longer exist.

6. Task hygiene

Scan stale or blocked tasks:

task status:pending list

Check for:

• Stale tasks: pending tasks that haven't been touched recently and may be obsolete
• Duplicate tasks: multiple tasks describing the same work
• Missing project/tags: tasks without a project: or category tag
• Blocked tasks: tasks waiting on a dependency that's already done

For larger findings, file a task instead of fixing inline: task add "<title>" project:<repo> +maintenance. For each finding, suggest an action (delete, merge, tag, etc.) but do not delete tasks without user confirmation.

7. Build artifact cleanup

Check for build artifacts or temp files that shouldn't be tracked:

git status --ignored --short 2>/dev/null | head -20

Verify .gitignore covers common patterns for the detected languages.

8. Print maintenance report

Print a summary using this format:

Maintenance Report
==================

Dependencies:     [OK | N outdated | N vulnerable]
Lint:             [OK | N warnings | N errors]
Format:           [OK | N files need formatting]
Tests:            [N passed, N failed, N skipped]
Dead code/TODOs:  [OK | N items found]
Documentation:    [OK | N files stale]
Task hygiene:     [OK | N tasks need attention]
Build artifacts:  [OK | N items to clean]

Actions taken:
  - Fixed N lint warnings
  - Removed N dead code items
  - Created N maintenance tasks

Recommended follow-ups:
  - <list of items that need human attention>

Constraints

• Do not make breaking changes. Maintenance is conservative — fix warnings, remove dead code, update docs.
• Do not update dependency versions without checking for breaking changes first. Report outdated deps; only update patch versions automatically.
• Do not delete tasks without user confirmation — only suggest closures.
• Do not modify test behavior — only fix test infrastructure issues (imports, configs).
• If a fix would touch more than 10 lines, create a task for it instead of fixing inline.