audit

name	audit
user-invocable	true
description	Repo-health audit and drift classifier for Green Goods — dead code, dependency health, invariant drift, stale guidance/plans/docs drift, and concrete broken or brittle spots. Use when the user asks for an audit, a drift check, "is the repo healthy", stale guidance, cleanup readiness, or whether to run clean. Read-only; routes accepted findings to a fix pass, /clean, or Linear.
argument-hint	[package|drift] [--full] [--team] [--loop]
context	fork
effort	high

Audit Skill

Systematic repo-health analysis: dead code detection, dependency health, invariant drift, and concrete brittle spots.

Prefer /review or /status first. This skill is for broader repo-health drift, not for every change or every question.

References: See CLAUDE.md for codebase patterns and .claude/context/*.md for per-package invariants.

Context mode: context: fork -- read-only subagent. Never edit files during an audit. Return findings in the response and let the user decide.

---

Scope Lock

This skill is strictly read-only by default, including report generation.

Audit/report work stays read-only by default. Do not create or mutate Linear records during analysis. After the user approves specific findings for tracking, route accepted findings into Linear Issues, not GitHub's issue tracker.

What This Skill Owns

• dead code and unused export detection
• dependency health and outdated package surfacing
• concrete invariant drift against repo rules
• brittle runtime or maintenance hotspots with direct evidence

What This Skill Does Not Own

• abstract architecture or design-soundness judgment (/review's boundary + coherence lenses)
• PR-scoped correctness review (review)
• implementation or refactor orchestration

False-Positive Guardrails

These are mandatory:

• only report issues with concrete runtime, correctness, or clear maintenance cost
• do not recommend new abstractions, patterns, or layers from this skill
• do not treat file size alone as a finding
• if a structural concern is mostly about design judgment, route it to /review (boundary/coherence lenses) instead of reporting it here
• cap medium and low-severity findings to the highest-signal set a human can act on

---

Activation

Trigger	Action
/audit	Full codebase audit
/audit [package]	Targeted package audit
/audit drift [scope]	Quick drift classification only (see Drift Mode)
"repo drift", "stale guidance", "should we clean?"	Treat as /audit drift
/audit --full	Skip scope detection, analyze all packages
/audit --team	Parallel agent team
/audit --loop	Complete the read-only audit, then route approved findings through the scope-lock rhythm (see Part 10)

Drift Mode

/audit drift [scope] is the fast, read-only classifier (formerly the standalone drift skill). It does not run Parts 0-10.

1. Run bun run drift:check -- --scope <scope> (scopes: all, guidance, plans, design, docs, cleanup, quality; add --json for machine output).
2. Report numbered findings with category, severity, evidence, and recommended route. Treat WARN output as a finding; include working-tree context if the checker reports a dirty tree.
3. Stop for human scope lock before fixing anything.

Routing: guidance/plans/docs drift → a scoped fix pass after the user approves findings by number (plan mode for anything large); design-system drift → /review --scope design-system; cleanup-shaped findings → recommend clean --scope <scope> --dry-run first, never full /clean without approval; anything that looks like a production bug, broken flow, or data/API/indexer failure → debug, not cleanup.

Progress Tracking (REQUIRED)

Use TodoWrite when available, otherwise Markdown checklist. See CLAUDE.md Session Continuity.

---

Part 0: Previous Findings Verification

REQUIRED before new analysis. Check current accepted tracking before claiming a finding is new or chronic.

1. If the user requests a follow-up or trend comparison, query current Linear issues in the approved scope. Otherwise record "no prior live comparison requested" and continue.
2. Re-verify relevant Critical/High tracked findings against current code.
3. For unchanged packages (per Part 0.5), carry forward only findings that still have a current Linear owner; spot-check 1-2 representative findings.
4. Use the Linear decision and issue age as context. Do not synthesize review cycles from deleted report files or revive resolved findings from Git history.
5. Include a Previous Findings Status table only when current tracked findings exist.

Finding statuses: STILL OPEN | FIXED | PARTIALLY FIXED | ACCEPTED | DEFERRED | MONITORED | CARRY-FORWARD (unchanged) | Downgraded to [severity]

---

Part 0.5: Change Scope Detection

Gates the expensive Parts 1-4 to only run on packages that actually changed.

Override: /audit --full skips scope detection.

1. Resolve a comparison base from the user's requested ref or the current PR base. If neither exists, treat all packages in scope as changed rather than inventing a baseline.
2. Compute changed packages:

git diff --name-only <last-audit-commit>..HEAD | grep '^packages/' | cut -d/ -f2 | sort -u

3. Classify: CHANGED (source files modified: .ts, .tsx, .sol, .graphql) vs UNCHANGED (ignore lockfiles, config-only, formatting-only diffs)
4. Output a scope table:

Package	Status	Changed Files	Action
shared	CHANGED	12	Full analysis (Parts 1-4)
contracts	UNCHANGED	0	Carry-forward + spot-check

5. CHANGED packages get full Parts 1-4. UNCHANGED packages: carry forward findings, spot-check 1-2 high-severity items, run bunx knip --workspace <pkg>.
6. First audit (no prior baseline): treat all packages as CHANGED.

---

Part 1: Automated Analysis

Run checks on CHANGED packages and capture output for later parts.

Build & Lint

bun run --filter '@green-goods/admin' build
bun run --filter '@green-goods/client' build
bun run --filter '@green-goods/agent' typecheck
bun lint
bash .claude/scripts/validate-hook-location.sh
# i18n gate: 4-part locale coverage (parity, counts, source-usage, identical-string quality)
bun run --filter '@green-goods/shared' test src/__tests__/i18n/locale-coverage.test.ts
grep -rn "TODO\|FIXME\|HACK" --include="*.ts" packages/

Dependency Health

bun audit --audit-level=high
bun outdated

Report: HIGH/CRITICAL CVEs as findings, deps 2+ major behind as LOW, deprecated/EOL as MEDIUM. If registry/network access is unavailable, record the dependency check as blocked; never install fallback tooling during an audit.

Test Coverage

bun run --filter '@green-goods/shared' test -- --coverage --reporter=json
bun run --filter '@green-goods/client' test -- --coverage --reporter=json
bun run --filter '@green-goods/admin' test -- --coverage --reporter=json
bun run --filter '@green-goods/agent' test -- --coverage --reporter=json

Extract per package: overall coverage %, files with 0% coverage, files below 50% branch coverage. Cross-reference zero-coverage files against god objects in Part 4 (low coverage + god object = higher risk).

For contracts: forge coverage if available, otherwise note "coverage not measured."

---

Part 2: File-by-File Review

For each file in CHANGED packages, check:

1. Deprecations -- outdated patterns, old APIs
2. Unfinished work -- TODO comments with staleness
3. Architectural violations (per CLAUDE.md): hooks in client/admin, package .env files, hardcoded addresses, undeclared shared/src/** internal imports
4. Type problems -- any, unknown, type assertions
5. Code smells -- long functions, deep nesting
6. Bare catch blocks -- classify each:
   • Intentional-with-fallback: Has fallback/logging/user error handling. NOT a finding.
   • Already-logged: Calls logger.warn/error. LOW at most.
   • Empty-swallow: Empty {} or comment-only. MEDIUM (mutation path) or LOW (UI path).
   • Only report empty-swallow and unlogged-mutation-path catches.

Severity Levels

• CRITICAL: Security issues, data loss risk
• HIGH: Bugs, broken functionality
• MEDIUM: Tech debt, maintainability
• LOW: Style, minor improvements

Risk Prioritization

Use risk score = Impact x Likelihood. Issue age from current Linear tracking may be noted separately, but does not mechanically change severity.

Factor	Values
Impact	4=Critical, 3=High, 2=Medium, 1=Low
Likelihood	3=Certain, 2=Likely, 1=Unlikely
Score < 4: report as-is. Score 4-8: prioritize for review. Score > 8: flag in
the Executive Summary. ACCEPTED, DEFERRED, and MONITORED findings retain their
current Linear decision unless the user explicitly reopens it.

Security Skill Integration (contracts only)

When auditing packages/contracts/, apply the security checklist in .claude/context/contracts.md:

1. Solidity security patterns against modified .sol files
2. Access control against files with onlyHatWearer, _authorizeUpgrade, role-check modifiers
3. UUPS upgrade safety (storage gaps, _authorizeUpgrade) if proxy/upgradeable contracts modified
4. Prefix security findings with SEC-

---

Part 3: Dead Code Detection

IMPORTANT: Always use knip for dead code detection. Never rely on grep-based scanning for unused exports (~80% false-positive rate in this monorepo).

bunx knip                          # Full analysis
bunx knip --reporter compact       # Condensed output
bunx knip --include files          # Only unused files
bunx knip --include exports        # Only unused exports
bunx knip --include dependencies   # Only unused deps

The knip.ts config already excludes packages/contracts/lib/, packages/indexer/generated/, and build outputs.

Manual fallback (non-TS files, Solidity only): grep for exports, search for usage, categorize as Dead / Possibly Dead / Active.

---

Part 4: Architectural Anti-Patterns

Anti-Pattern	Detection
God Objects	Files > 500 lines, cross-ref with coverage data from Part 1
Circular Deps	Import cycles
Layer Violations	Wrong import direction

God objects: include coverage %. Zero-coverage god objects escalate one additional risk level.

Green Goods Violations

grep -rn "^export.*use[A-Z]" packages/client packages/admin    # Hooks outside shared
find packages -name ".env*" -not -path "*/node_modules/*"       # Package .env files
grep -rn "0x[a-fA-F0-9]\{40\}" packages/ --include="*.ts" | grep -v __tests__  # Hardcoded addresses
grep -rn "@green-goods/shared/src" packages/client packages/admin packages/agent packages/indexer --include="*.ts*"  # Undeclared shared internals

Cap the anti-patterns table at top 10 by risk score. Do not create a local overflow registry; offer the remaining accepted findings for Linear tracking.

---

Part 5: Self-Validation (REQUIRED before report)

Re-verify EVERY finding from Parts 1-4:

1. Re-read the flagged file at the cited line
2. Confirm code matches the finding description
3. Check 10 lines above/below for guards/comments that invalidate the finding
4. Assign confidence: HIGH / MEDIUM / LOW -- drop LOW confidence findings
5. Verify escalation was applied where required (score 4.0-8.0 bumped, score > 8.0 in summary)
6. Verify catch block classification (only dangerous catches reported)
7. Verify security integration for contracts (SEC-prefixed findings included)

In team mode, the lead re-reads every sub-agent finding before synthesis. Unverifiable findings get dropped.

---

Part 6: Report Generation

Return the report in the response. If the user explicitly requests a durable artifact, use an existing feature hub report when the audit is feature-specific; otherwise route accepted work to Linear rather than creating a generic audit folder. Report shape:

# Audit Report - [Date]

## Executive Summary
- **Packages analyzed**: [list] | **Mode**: Single-agent | Team | **Baseline**: [commit range]
- **Critical**: N | **High**: N | **Medium**: N | **Low**: N
- **Security (contracts)**: SEC-Critical: N | SEC-High: N | SEC-Medium: N
- **Dead code**: N unused files, N unused exports, N unused types, N unused deps
- **Tests**: [pass counts] | **Coverage**: shared N% / client N% / admin N%
- **Dependency health**: N vulnerabilities (H/C), N outdated (2+ major)

### Highest-risk findings (risk score > 8)
### Executive Delta (when a live comparison was requested)
- Packages changed/unchanged, tracked findings opened/closed/net, and key changes

---

## Previous Findings Status
| ID | Finding | File | Status | Risk Score | Notes |

## Security Findings (contracts)
### SEC-H1. [Title]
- File, checklist, issue, recommendation

## High / Medium / Low Findings
### H1. [Title] ([STILL OPEN | NEW])
- **File** | **Risk score** | **Issue** | **Recommendation**

## Skill & Configuration Drift
| Reference | Location | Status |

## Architectural Anti-Patterns (top 10 by risk score)
| Anti-Pattern | Location | Lines | Coverage | Risk Score | Severity |

## Dependency Health
| Category | Count | Details |

## Tracked-finding delta (when current Linear history exists)
| Metric | Previous live state | Current |

## Recommendations (Priority Order)
1. **[Action]** -- (Severity, finding ID, risk score)

---

Part 7: Skill & Configuration Drift Detection

Run the consolidated drift check:

bash .claude/scripts/check-drift.sh

Checks: hook/utility/type references in skills vs actual shared exports, dev port assignments, core commands in package.json, .env.schema key variables.

Manual check: Provider order -- compare actual provider nesting in client/admin against documented order (MEDIUM if drifted).

---

Part 8: Team Mode

When --team is passed, spawn parallel agents. Requires the Agent tool (fall back to single-agent if unavailable).

Scope-Aware Spawning

Only spawn agents for CHANGED package groups. Lead handles carry-forward for UNCHANGED packages. /audit --full --team spawns all agents regardless.

Team Structure

Lead (Parts 0, 0.5, 5-7, 9 -- scope, validation, report, drift, triage)
  [if contracts/indexer CHANGED]  chain-auditor      (Parts 1-4)
  [if shared CHANGED]             middleware-auditor  (Parts 1-4)
  [if client/admin/agent CHANGED] app-auditor         (Parts 1-4)

Each agent runs Parts 1-4 scoped to their packages using bunx knip --workspace. Agents must NOT read files outside their scope; cross-package findings are marked "needs cross-package verification." The lead validates all sub-agent findings before synthesis.

---

Part 9: Triage & Routing

After the report, group findings by actionability:

Category	Criteria	Output
Fix Now	Critical/High, risk > 8.0	Individual Linear issue per accepted finding
Fix Soon	Medium, risk 4.0-8.0	Batch into 1 Linear issue per package when accepted
Track	Low or MONITORED	Keep in response; offer Linear tracking after approval
Accept	ACCEPTED/DEFERRED	No action

Prompt user before creating any Linear issues: "Found N findings that are ready to track in Linear. Create Product/Research issues for these accepted findings? [y/n]"

Only after explicit approval should accepted findings be persisted to current Linear issues. Do not create or update a parallel repository registry.

Linear Issue Routing

Team routing (Product vs Research vs Customer Need), .plans/source:plans linkage, project routing, label namespaces, prompt-before-create, and the privacy boundary follow the shared core: .claude/context/linear-routing-rules.md.

Audit-specific deltas:

• Issue bodies include the relevant Greenpill template sections: Outcome or Research question, Protocol context, Scope boundary or Evidence to gather, Acceptance criteria or Expected output, Validation or Routing recommendation, Privacy note when applicable, and Links.
• Findings originate in the current audit response; accepted tracking lives in Linear.

---

Part 10: Implementation Handoff

When --loop is requested, complete the read-only audit first and present numbered findings. Route the approved set through the scope-lock rhythm (numbered findings → explicit user lock → fix only locked items → re-validate per .claude/context/validation-pipeline.md). Do not apply fixes, create branches, write reports, or update registries from the audit phase itself. Fix at most 3 findings per approved iteration, highest risk score first, on the current branch.

---

Anti-Patterns

Don't	Why
Flag packages/contracts/lib/ as dead code	Foundry git submodules -- excluded by knip.ts
Flag indexer handlers as unused	Envio runtime imports -- knip.ts entry points
Report god objects in multiple sections	Use Anti-Patterns table only; reference from findings
Count generated files in unused totals	Build artifacts, not source
Use grep to detect unused exports	~80% false-positive rate
Use haiku-class models for audit	95% false-positive rate -- use opus
Include LOW-confidence findings	Self-validation gate drops them
Edit files during an audit	Read-only mode
State cross-package findings as confirmed	Mark "needs cross-package verification"
Skip current tracked-findings check when trend was requested	A stale local report is not a substitute for live tracking
Report 24+ god object rows	Keep the response to the top 10; offer accepted overflow findings for Linear
Count intentional catch-with-fallback as bare catch	Classify per Part 2; only report dangerous ones
Skip security skill for contracts	Part 2 requires explicit security invocation
Create Linear issues without prompting	Part 9 requires user confirmation
Run full analysis on unchanged packages	Part 0.5 gates analysis to changed packages
Fix more than 3 findings per loop iteration	Prevents context exhaustion
Fix design-level problems via /audit --loop	Design judgment belongs in /review's coherence lens

---

Key Principles

• Complete all files within scope -- never skip
• Scope-aware -- diff detection limits analysis to changed packages
• Read-only -- don't edit during audit
• Evidence-based -- every finding needs file:line and risk score
• Risk-weighted -- prioritization uses impact x likelihood
• Prompt before issues -- ask user before creating Linear issues
• Live-tracked -- accepted findings live in current Linear issues, not local report folders

Boundary

If it's about what's broken, dead, or drifted — audit. If it's about whether one change is sound — /review (its coherence and boundary lenses replaced the retired principles/architecture skills).

Related Skills

• review — diff-scoped correctness, coherence, and boundary judgment
• clean — broad cleanup after audit findings prove cleanup-shaped
• debug — when a finding is really a runtime/product failure
• plan — stale or inconsistent .plans truth