Codebase Audit

Codebase Audit → Issue → Worktree Fix → PR

End-to-end workflow: systematically review the entire codebase, report findings as GitHub issues, fix each issue in an isolated git worktree, and submit PRs — all in one session.

When to use this skill

Use this skill when you need to:

• Perform a full code review / audit of the codebase
• Proactively find security vulnerabilities, logic bugs, or code quality problems
• Turn code review findings into tracked GitHub issues
• Fix each issue in isolation (worktree per issue) and submit PRs
• Run a periodic codebase health check with automated follow-through
• Audit and fix dependency security vulnerabilities (Dependabot alerts / npm audit)

Do NOT use for:

• Reviewing or fixing a single known bug (use systematic-debugging or direct fix)
• Triaging existing open PRs (use pr-review-fix)
• Processing attribution issues (use mcp-attribution-worktree)
• Feature development or refactoring unrelated to audit findings

Workflow

Phase 1 — Review

1. Read references/review-strategy.md for the review scope and checklist. 2. Use the code-explorer subagent to read ALL source files in the target directory (default: mcp/src/). 3. For each file, systematically check against the review checklist:

• Security: path traversal, injection, unvalidated input, hardcoded secrets, improper error exposure
• Error handling: missing try-catch, swallowed errors, error messages leaking internals
• Type safety: as any, unsafe casts, missing null checks
• Logic bugs: race conditions, incorrect conditionals, unreachable code
• Code quality: dead code, duplication, overly complex functions
• Resource leaks: unclosed connections, missing cleanup
• API design: inconsistent validation, missing required field checks

4. Record every finding with: file path, line number(s), category, severity (Critical/High/Medium/Low), description, and suggested fix. 5. Dependency scan: Read references/dependency-audit.md and run the Dependabot alert fetch + npm audit to discover vulnerable dependencies. Record each finding using the dependency-audit format.

Phase 2 — Analyze & Classify

1. Read references/classification.md for severity definitions and grouping rules. 2. Deduplicate findings — merge instances of the same pattern across files. 3. Group findings into fix batches — related issues that should be fixed together in one PR. 4. Assign severity and priority:

• P0 (Critical): Security vulnerabilities, data loss risks
• P1 (High): Logic bugs, error handling gaps that cause runtime failures
• P2 (Medium): Type safety, code quality issues affecting maintainability
• P3 (Low): Style, naming, minor cleanup

5. Present a structured audit report to the user and wait for confirmation before proceeding.

Phase 3 — Create GitHub Issues

1. Read references/issue-workflow.md for issue creation guidelines. 2. For each fix batch (or individual Critical finding), create a GitHub issue:

   gh issue create --title "<type>(<scope>): <summary>" --body "<structured body>" --label "<severity>,<category>"

3. Issue body must include: affected files, line numbers, problem description, expected behavior, and suggested fix approach. 4. Link related issues when findings are connected. 5. Present the created issues to the user.

Phase 4 — Worktree Fix

1. Read references/worktree-fix.md for the isolation and fix procedure. 2. For each issue (in priority order): a. Create an isolated worktree and branch:

      git worktree add ../<repo>-audit-fix-<issue-number> -b fix/<slug>-<issue-number> origin/main

b. Work inside the worktree — never in the main checkout. c. Implement the fix, keeping changes minimal and focused. d. Verify locally: cd mcp && npm run build && npm run test e. Commit with conventional-changelog format:

      git commit -m 'fix(<scope>): 🔒 <english description>

      Closes #<issue-number>'

f. Push and create PR:

      git push github fix/<slug>-<issue-number>
      gh pr create --title "fix(<scope>): 🔒 <summary>" --body "Closes #<issue-number>\n\n<description>" --base main

g. Remove the worktree after PR is created:

      cd <original-dir>
      git worktree remove ../<repo>-audit-fix-<issue-number>

3. One worktree per issue. Never mix fixes across worktrees. 4. Dependency fixes: For dependency vulnerability batches, follow references/dependency-audit.md Step 4. These can be grouped into a single PR since they modify package.json / package-lock.json.

Phase 5 — Verify & Report

1. Read references/verification.md for the verification checklist. 2. Check CI status for each PR:

   gh pr checks <number>

3. If CI fails, re-enter the worktree, fix, and push again. 4. Generate a final audit report summarizing:

• Total findings by category and severity
• Issues created (with links)
• PRs submitted (with links)
• Remaining items that need human decision

Routing

Git safety rules

• Never force-push unless explicitly asked.
• Never amend commits that are already pushed.
• Always work inside the worktree, not the main checkout.
• Always verify build + test locally before pushing.
• One worktree per issue — never mix fixes.
• Clean up worktrees after PR creation.

Commit conventions

Follow the project's conventional-changelog format:

fix(<scope>): 🔒 <english description>

Closes #<issue-number>

Scope examples: security, deps, error-handling, type-safety, code-quality, cloudrun, database, functions

Minimum self-check

• Did I review ALL source files in the target scope, not just a sample?
• Did I categorize each finding with file, line, severity, and description?
• Did I present the audit report and get user confirmation before creating issues?
• Did I create a separate GitHub issue for each fix batch?
• Did I use an isolated worktree for each fix, not the main checkout?
• Did I verify build + test pass before pushing each fix?
• Did I clean up worktrees after creating PRs?
• Did I generate a final report with links to all issues and PRs?
• Did I check Dependabot alerts and npm audit for dependency vulnerabilities?
• Did I apply the correct fix strategy (upgrade / override / replace / dismiss) for each vulnerable dependency?

Classification & Batching

Severity definitions

Deduplication rules

Many findings are instances of the same pattern across different files. Deduplicate aggressively:

1. Same root cause: If multiple files have the same type of issue (e.g., all using as any to bypass a shared type), merge into one finding with multiple locations. 2. Same fix: If the fix is identical across locations (e.g., adding null check before .property), group them. 3. Related chain: If fixing A automatically fixes B (e.g., fixing a shared utility also fixes all callers), note the dependency.

After deduplication, the finding list should be actionable — each entry represents one distinct thing to fix.

Batching into fix groups

Group findings into fix batches for PR submission. Each batch becomes one GitHub issue and one PR.

Batching rules

1. Security findings — one batch per vulnerability type (e.g., "path traversal" batch, "input validation" batch). Critical findings can be individual batches. 2. Same-file fixes — if 3+ findings are in the same file and related, batch them. 3. Same-pattern fixes — if the same fix pattern applies across 5+ files (e.g., adding error handling to all tool handlers), batch them. 4. Independent fixes — findings with no relationship get their own batch.

Batch size limits

• Maximum 10 files changed per batch (keeps PRs reviewable).
• Maximum 1 Critical + related findings per batch (don't bury critical fixes).
• If a batch grows too large, split by subdirectory or by sub-pattern.

Priority ordering

Within each severity level, prioritize by:

1. Attack surface: externally-reachable code (tool handlers, API endpoints) before internal utilities 2. Usage frequency: hot paths before rarely-executed branches 3. Fix confidence: straightforward fixes before ones requiring design decisions 4. Blast radius: fixes touching shared code (affects many callers) before isolated fixes

Audit report format

Present findings to the user in this structure:

# Codebase Audit Report — <date>

## Summary

- Total findings: N
- Critical: X | High: Y | Medium: Z | Low: W
- Unique patterns: N (after deduplication)
- Fix batches: N

## Critical findings

### [C1] <title>
- **Files**: <list>
- **Description**: <what and why>
- **Suggested fix**: <approach>
- **Batch**: #1

## High findings

### [H1] <title>
...

## Medium findings
...

## Low findings
...

## Proposed fix batches

| Batch | Issues | Severity | Files | Description |
|-------|--------|----------|-------|-------------|
| #1 | C1, H3 | Critical | 5 | Security: path traversal fixes |
| #2 | H1, H2 | High | 3 | Error handling in tool handlers |
| ... | ... | ... | ... | ... |

## Recommended action

1. Fix batch #1 first (Critical security)
2. Then batch #2 (High error handling)
3. ...

Wait for user confirmation before proceeding to issue creation.

Dependency Security Audit

Overview

This reference covers how to discover, triage, and fix dependency-level security vulnerabilities reported by GitHub Dependabot (or npm audit). It complements the source-code review in review-strategy.md.

Step 1 — Fetch alerts

GitHub Dependabot alerts (preferred)

gh api repos/<owner>/<repo>/dependabot/alerts \
  --jq '.[] | select(.state=="open") | {number, severity: .security_vulnerability.severity, package: .dependency.package.name, ecosystem: .dependency.package.ecosystem, summary: .security_advisory.summary, ghsa: .security_advisory.ghsa_id, patched: .security_vulnerability.first_patched_version.identifier, manifest: .dependency.manifest_path}' \
  | cat

npm audit (fallback / local)

cd <project-root> && npm audit --json 2>/dev/null | head -500

Use Dependabot alerts as the primary source — they track advisory state and dismissal. npm audit is a supplementary check for unlisted transitive issues.

Step 2 — Aggregate & prioritise

1. Group by package — multiple alerts for the same package should be fixed together. 2. Sort groups by highest severity within the group:

• Critical → fix immediately
• High → fix in current session
• Medium → fix if straightforward, otherwise create issue
• Low → create issue for tracking, may dismiss with justification

3. Identify dependency depth — determine whether the vulnerable package is a direct or transitive dependency:

   npm ls <package-name> 2>/dev/null | head -20

4. Check current locked version:

   jq '.packages | to_entries[] | select(.key | contains("<package-name>")) | {key, version: .value.version}' package-lock.json

Step 3 — Choose fix strategy

Use this decision tree for each package group:

Is the package a direct dependency?
├─ YES → Can we upgrade to a patched version without breaking changes?
│        ├─ YES → Strategy A: Direct upgrade
│        └─ NO  → Is the package still maintained?
│                  ├─ YES → Strategy B: Major version upgrade (check changelog for breaking changes)
│                  └─ NO  → Strategy C: Replace with alternative package
└─ NO (transitive) → Can the parent dependency be upgraded to pull in the fix?
                      ├─ YES → Strategy A: Upgrade parent dependency
                      └─ NO  → Strategy D: npm overrides

Strategy A — Direct upgrade

npm install <package>@<patched-version> --save       # direct dep
npm install <parent-package>@<latest> --save          # transitive via parent
npm audit fix                                          # let npm attempt auto-fix

After upgrade, verify:

npm ls <package-name>           # confirm version resolved
npm run build && npm run test   # confirm no breakage

Strategy B — Major version upgrade

1. Read the package changelog / migration guide. 2. Identify breaking changes relevant to current usage. 3. Update call sites as needed. 4. Run full build + test.

Strategy C — Replace with alternative

1. Identify an actively maintained alternative with equivalent functionality. 2. Update import paths and usage across the codebase. 3. Remove the old package: npm uninstall <old-package>. 4. Run full build + test.

Strategy D — npm overrides (transitive only)

When the parent package hasn't released a fix, use overrides in package.json:

{
  "overrides": {
    "<vulnerable-package>": "<patched-version>"
  }
}

For scoped transitive overrides (only override within a specific parent):

{
  "overrides": {
    "<parent-package>": {
      "<vulnerable-package>": "<patched-version>"
    }
  }
}

After adding overrides:

rm -rf node_modules package-lock.json
npm install
npm ls <vulnerable-package>     # confirm override applied
npm run build && npm run test   # confirm no breakage

Caution: Overrides can break the parent package if the patched version has incompatible API changes. Always test thoroughly.

Strategy E — Dismiss with justification

If the vulnerability is not exploitable in the project's context (e.g., a server-side ReDoS in a package only used at build time with trusted input), dismiss the alert:

gh api repos/<owner>/<repo>/dependabot/alerts/<number> \
  -X PATCH \
  -f state=dismissed \
  -f dismissed_reason="not_used" \
  -f dismissed_comment="<explanation of why this is not exploitable in our context>"

Valid dismissed_reason values: fix_started, inaccurate, no_bandwidth, not_used, tolerable_risk.

Rule: Never dismiss Critical or High alerts without explicit user approval.

Step 4 — Execute fixes

Follow the same worktree isolation process as worktree-fix.md:

1. Create a single worktree + branch for all dependency fixes (they typically go in one PR):

   git worktree add ../<repo>-dep-fix -b fix/security-vulnerabilities-<issue-number> origin/main
   cd ../<repo>-dep-fix

2. Apply fixes (upgrade / override / replace). 3. Regenerate lockfile: npm install. 4. Verify: npm run build && npm run test. 5. Commit:

   git add package.json package-lock.json
   git commit -m 'fix(deps): 🔒 upgrade vulnerable dependencies

   Closes #<issue-number>'

6. If code changes were needed (strategy B/C), commit them separately with descriptive messages. 7. Push and create PR.

Step 5 — Verify resolution

After the PR is merged:

gh api repos/<owner>/<repo>/dependabot/alerts \
  --jq '[.[] | select(.state=="open")] | length'

Expected: the count should decrease by the number of fixed alerts.

Also re-run:

npm audit

Recording findings

For each vulnerable dependency group, record:

Package: <name>
Alerts: #<number1>, #<number2>, ...
Severity: <Critical|High|Medium|Low> (highest in group)
Current version: <locked version>
Patched version: <target version>
Dependency depth: <direct|transitive via X>
Strategy: <A|B|C|D|E>
Status: <fixed|dismissed|deferred>
Notes: <any context>

Common patterns

Issue Creation Workflow

Prerequisites

• gh CLI authenticated: gh auth status
• Remote github configured and reachable

Issue template

Each fix batch maps to one GitHub issue.

Title format

<type>(<scope>): <summary>

Examples:

• fix(security): 🔒 Path traversal vulnerabilities in file operation tools
• fix(error-handling): 🛡️ Missing error handling in tool handlers
• fix(type-safety): 🔧 Unsafe type casts across database tools
• fix(code-quality): 🧹 Dead code and duplication in cloudrun module

Body structure

## Problem

<1-2 sentence summary of what's wrong and why it matters>

## Affected files

| File | Lines | Issue |
|------|-------|-------|
| `mcp/src/tools/foo.ts` | 42-55 | Missing input validation |
| `mcp/src/tools/bar.ts` | 100-120 | Same pattern |

## Severity

**<Critical|High|Medium|Low>** — <one sentence justification>

## Suggested fix

<Concrete description of the fix approach. Include code snippets when helpful.>

## Acceptance criteria

- [ ] All affected files updated
- [ ] Build passes: `npm run build`
- [ ] Tests pass: `npm run test`
- [ ] No new `as any` or unsafe casts introduced
- [ ] <Additional criteria specific to this issue>

## Context

Found during codebase audit on <date>.
Related findings: #<other-issue-numbers> (if any)

Creating the issue

gh issue create \
  --repo <owner>/<repo> \
  --title "fix(<scope>): 🔒 <summary>" \
  --body "$(cat /tmp/issue-body.md)" \
  --label "bug,<severity>"

Tips:

• Write the body to a temp file first to avoid shell escaping issues.
• Add labels: bug + severity (critical, high, medium, low) + category (security, error-handling, type-safety, code-quality).
• If labels don't exist yet, create them or skip labeling.

Linking related issues

When findings are related (e.g., same root cause manifesting differently):

# Add a cross-reference in the body
"Related to #<number>"

Batch creation

When creating multiple issues in one session:

1. Create issues in priority order (Critical first). 2. Track created issue numbers. 3. After all issues are created, present a summary table:

## Issues created

| # | Title | Severity | Files |
|---|-------|----------|-------|
| #101 | fix(security): Path traversal | Critical | 5 |
| #102 | fix(error-handling): Missing catches | High | 3 |

4. Confirm with user before proceeding to fix phase.

Rate limiting

GitHub API has rate limits. If creating many issues:

• Pause 2 seconds between issue creation calls.
• If rate-limited, wait and retry.
• Maximum 10 issues per session to keep things manageable.

Review Strategy

Scope

Default target: mcp/src/ (all TypeScript files). The user can override this.

Before starting, confirm the scope:

find <target-dir> -name '*.ts' -not -path '*/node_modules/*' | wc -l

Approach

Use the code-explorer subagent for large-scale file reading. Send it a prompt that covers ALL files and ALL categories in one pass. Do NOT sample — read every file.

If the target has more than 50 files, split into batches by subdirectory and launch parallel subagents.

Review checklist

For every file, check each category below. Not every category applies to every file — skip inapplicable ones but never skip a file.

1. Security (Critical priority)

2. Error handling (High priority)

3. Type safety (Medium priority)

4. Logic bugs (High priority)

5. Code quality (Medium priority)

6. Resource management (High priority)

7. API design (Medium priority)

Recording findings

For each finding, capture:

File: <path>
Lines: <start>-<end>
Category: <Security|Error handling|Type safety|Logic|Quality|Resource|API>
Severity: <Critical|High|Medium|Low>
Title: <one-line summary>
Description: <what's wrong and why it matters>
Suggested fix: <concrete code change or approach>

Group related findings (same root cause across files) into a single entry with multiple locations listed.

Verification & Final Report

Post-push CI verification

After pushing each fix and creating a PR, verify CI:

# Wait ~2 minutes for CI to trigger
gh pr checks <number>

CI status handling

Re-fix loop

If CI fails after your push:

1. Read the failure log:

   gh run list --branch fix/<slug>-<N> --limit 1 --json databaseId --jq '.[0].databaseId'
   gh run view <run-id> --log-failed 2>/dev/null | tail -100

2. Re-enter the worktree:

   cd ../<repo>-audit-fix-<N>

3. Fix, verify locally, commit, push again. 4. Maximum 3 retry loops per issue. If still failing, note it in the report.

Final audit report

After all issues are processed, generate a comprehensive report:

# Codebase Audit Report — <date>

## Executive summary

- Files reviewed: N
- Total findings: N (Critical: X, High: Y, Medium: Z, Low: W)
- GitHub issues created: N
- PRs submitted: N
- PRs verified (CI passing): N

## Issues & PRs

| Issue | PR | Title | Severity | Status |
|-------|-----|-------|----------|--------|
| #101 | #201 | Path traversal fixes | Critical | ✅ CI passing |
| #102 | #202 | Error handling gaps | High | ✅ CI passing |
| #103 | — | Architecture concern | Medium | 📋 Issue only (needs discussion) |

## Findings not actioned

These findings were identified but not fixed in this session:

| Finding | Reason |
|---------|--------|
| <description> | Requires architectural decision |
| <description> | Low priority, deferred |

## Recommendations

1. <Strategic recommendation based on patterns observed>
2. <Process improvement suggestion>
3. <Areas to watch in future audits>

Report delivery

1. Save the report to the workspace (e.g., specs/audit-<date>/report.md). 2. Present it to the user via open_result_view. 3. Summarize key metrics in the chat message.

Audit completeness checklist

Before declaring the audit complete:

• [ ] All files in scope were reviewed (not sampled)
• [ ] All Critical and High findings have GitHub issues
• [ ] All actionable issues have PRs submitted
• [ ] All PRs have CI verification (pass or documented failure)
• [ ] Worktrees are cleaned up
• [ ] Final report is generated and presented
• [ ] User has been informed of any findings that need human judgment

Worktree Fix Procedure

Why worktrees

Each issue gets its own isolated worktree so that:

• Fixes don't interfere with each other.
• The main checkout stays clean for other work.
• Each PR has a clean diff tied to exactly one issue.
• If a fix goes wrong, only that worktree is affected.

Naming convention

Worktree directory: ../<repo-name>-audit-fix-<issue-number>
Branch name:        fix/<slug>-<issue-number>

Example: issue #101 about path traversal →

• Worktree: ../cloudbase-turbo-delploy-audit-fix-101
• Branch: fix/path-traversal-101

Pre-flight

Before starting any fix:

# 1. Note current branch and status
git branch --show-current
git status

# 2. Fetch latest
git fetch github

# 3. Verify no worktree conflicts
git worktree list

Fix loop (per issue)

Step 1 — Create worktree

git worktree add ../<repo>-audit-fix-<N> -b fix/<slug>-<N> github/main
cd ../<repo>-audit-fix-<N>

Important: All subsequent work happens inside this worktree directory.

Step 2 — Reproduce

Confirm the issue exists:

cd mcp
npm ci
npm run build 2>&1 | grep -i error
npm run test 2>&1 | grep -i fail

For security issues, reproduce with a mental walkthrough or unit test that exercises the vulnerable path.

Step 3 — Implement fix

Rules:

• Minimal changes — fix only what the issue describes.
• Don't mix concerns — no refactoring, no "while I'm here" improvements.
• Follow existing patterns — match the codebase's style and conventions.
• Add tests when appropriate — especially for security fixes and logic bugs.

Step 4 — Verify locally

cd mcp
npm run build    # must pass cleanly
npm run test     # all tests must pass

If verification fails: 1. Check if failure is from your change or pre-existing. 2. If from your change, fix it. 3. If pre-existing, note it but don't fix it in this PR.

Step 5 — Commit

git add <changed-files>
git commit -m 'fix(<scope>): 🔒 <english description>

Closes #<issue-number>'

Emoji conventions:

• 🔒 Security fixes
• 🛡️ Error handling improvements
• 🔧 Type safety / code quality fixes
• 🧹 Cleanup / dead code removal

Step 6 — Push and create PR

git push github fix/<slug>-<N>

gh pr create \
  --title "fix(<scope>): 🔒 <summary>" \
  --body "## Changes

<description of what was fixed and how>

## Affected files

<list of changed files>

## Testing

- [x] Build passes locally
- [x] All tests pass locally
- [x] No new warnings introduced

Closes #<issue-number>" \
  --base main

Push to GitHub by default per current project convention:

git push github fix/<slug>-<N>

Only push to other remotes when the user explicitly asks for it.

Step 7 — Clean up worktree

cd <original-repo-dir>
git worktree remove ../<repo>-audit-fix-<N>

If the worktree has uncommitted changes, force remove only if you're sure the work is pushed:

git worktree remove --force ../<repo>-audit-fix-<N>

Multi-issue session

When fixing multiple issues:

1. Complete the full loop for issue A before starting issue B. 2. Track progress with a checklist. 3. If two issues touch the same file, note the potential merge conflict but keep them in separate worktrees/PRs anyway. The second PR can be rebased after the first merges.

Handling failures

Safety guardrails

• Never work in the main checkout during the fix phase.
• Never force-push unless explicitly asked.
• Never amend pushed commits.
• Always verify before pushing.
• Always clean up worktrees after PR creation.
• One issue per worktree — no exceptions.