---
title: "Audit Full"
description: "Single-pass codebase analysis leveraging a 1M-token context window for comprehensive security scanning, architecture review, and dependency auditing. Loads entire codebases for cross-file pattern detection and generates structured audit reports with severity-ranked findings. Use when you need whole-project analysis before releases or security reviews."
canonical: "https://orchestkit.yonyon.ai/docs/reference/skills/audit-full"
---

# Audit Full

Single-pass codebase analysis leveraging a 1M-token context window for comprehensive security scanning, architecture review, and dependency auditing. Loads entire codebases for cross-file pattern detection and generates structured audit reports with severity-ranked findings. Use when you need whole-project analysis before releases or security reviews.

<span className="badge badge-gray">Reference</span> <span className="badge badge-red">max</span>

> **Auto-activated** — this skill loads automatically when Claude detects matching context.

<ContextualSkillSidebar slug="audit-full" />

> **Audit Full** Single-pass codebase analysis leveraging a 1M-token context window for comprehensive security scanning, architecture review, and dependency auditing. Loads entire codebases for cross-file pattern detection and generates structured audit reports with severity-ranked findings. Use when you need whole-project analysis before releases or security reviews.


# Full-Codebase Audit

Single-pass whole-project analysis leveraging Opus 5's extended context window. Loads entire codebases (~50K LOC) into context for cross-file vulnerability detection, architecture review, and dependency analysis.

## Quick Start

```bash
/ork:audit-full                          # Full audit (all modes)
/ork:audit-full security                 # Security-focused audit
/ork:audit-full architecture             # Architecture review
/ork:audit-full dependencies             # Dependency audit
```

> **Opus 5**: Uses `complexity: max` for extended thinking across entire codebases. 1M context (default and maximum on Opus 5) enables cross-file reasoning that chunked approaches miss. Effort defaults to `high`; bump to `xhigh` for one additional cross-file pattern sweep on the hardest codebases.

> **1M Context Required:** If `CLAUDE_CODE_DISABLE_1M_CONTEXT` is set, audit-full cannot perform full-codebase analysis. Check: `echo $CLAUDE_CODE_DISABLE_1M_CONTEXT` — if non-empty, either unset it (`unset CLAUDE_CODE_DISABLE_1M_CONTEXT`) or use `/ork:verify` for chunked analysis instead.

> **Effort (CC 2.1.111+):** `xhigh` adds a second pass that re-reads cross-module boundaries specifically looking for patterns the first pass normalized over. The Opus tier has defaulted to `high` since CC 2.1.154 and reserves `xhigh` for the hardest codebases. Silently falls back to `high` on other models; `/ork:doctor` warns on mismatch.

> **Switching to Opus (CC 2.1.144+):** `/model` now affects the current session only — pick Opus for this audit without it persisting. Press `d` in the picker only if you want it as the default for new sessions too.

---

## STEP 0: Verify User Intent with AskUserQuestion

**BEFORE creating tasks**, clarify audit scope using the interactive dialog.

Load: `Read("$\{CLAUDE_PLUGIN_ROOT\}/skills/audit-full/references/audit-scope-dialog.md")` for the full AskUserQuestion dialog with mode options (Full/Security/Architecture/Dependencies) and scope options (Entire codebase/Specific directory/Changed files).

---

## CRITICAL: Task Management is MANDATORY

```python
# 1. Create main task IMMEDIATELY
TaskCreate(
  subject="Full-codebase audit",
  description="Single-pass audit using extended context",
  activeForm="Running full-codebase audit"
)

# 2. Create subtasks for each phase
TaskCreate(subject="Estimate token budget and plan loading", activeForm="Estimating token budget")  # id=2
TaskCreate(subject="Load codebase into context", activeForm="Loading codebase")                    # id=3
TaskCreate(subject="Run audit analysis", activeForm="Analyzing codebase")                          # id=4
TaskCreate(subject="Generate audit report", activeForm="Generating report")                        # id=5

# 3. Set dependencies for sequential phases
TaskUpdate(taskId="3", addBlockedBy=["2"])  # Loading needs budget estimate
TaskUpdate(taskId="4", addBlockedBy=["3"])  # Analysis needs codebase loaded
TaskUpdate(taskId="5", addBlockedBy=["4"])  # Report needs analysis done

# 4. Update status as you progress
TaskUpdate(taskId="2", status="in_progress")  # When starting
TaskUpdate(taskId="2", status="completed")    # When done — repeat for each subtask
```

---

## STEP 1: Estimate Token Budget

Before loading files, estimate whether the codebase fits in context.

Load: `Read("$\{CLAUDE_PLUGIN_ROOT\}/skills/audit-full/references/token-budget-planning.md")` for estimation rules (tokens/line by file type), budget allocation tables, auto-exclusion list, and fallback dialog when codebase exceeds budget.

Run estimation: `bash $\{CLAUDE_PLUGIN_ROOT\}/skills/audit-full/scripts/estimate-tokens.sh /path/to/project`

### Two tiers — pick by the estimate

audit-full has **two execution tiers**. The estimate decides which:

| Estimate vs budget | Tier | Path |
|--------------------|------|------|
| **Fits** (~≤125K LOC / ≤1M tokens) | **Single-context** (default — the skill's edge: whole-codebase cross-file reasoning in one window) | continue to STEP 2 |
| **Exceeds** budget | **Map-reduce** (scale tier — shard → per-shard audit → cross-shard boundary synthesis → refute) | invoke the workflow below; STEP 2–3.5 run *inside* it |

**Over-budget → run the map-reduce workflow** (don't punt, don't silently truncate the load):

```python
# Derive shards from STEP 1 (top-level modules/dirs by size: src, apps/api, apps/web, packages/*).
Workflow({
  "scriptPath": "${CLAUDE_PLUGIN_ROOT}/skills/audit-full/workflows/audit-full-mapreduce.js",
  "args": { "shards": ["<repo-relative dirs>"], "mode": "<full|security|architecture|dependencies>", "effort": "<high|xhigh>" }
})
```

It preserves cross-file reasoning *within* each shard and recovers cross-*shard* edges (taint/auth/dep-direction that span modules) in a dedicated synthesis pass, then runs the same STEP 3.5 adversarial refutation. Its return (merged findings + refutation ledger) feeds STEP 4. The single-context tier remains the default because it's cheaper and loses no boundaries when the repo fits — only reach for map-reduce when it genuinely doesn't.

---

## STEP 2: Load Codebase into Context

Load: `Read("$\{CLAUDE_PLUGIN_ROOT\}/skills/audit-full/references/report-structure.md")` for loading strategy, inclusion patterns by language (TS/JS, Python, Config), and batch reading patterns.

---

## STEP 3: Audit Analysis

With codebase loaded, perform the selected audit mode(s).

### Security Audit

Load: `Read("$\{CLAUDE_PLUGIN_ROOT\}/skills/audit-full/references/security-audit-guide.md")` for the full checklist.

Key cross-file analysis patterns:
1. **Data flow tracing**: Track user input from entry point → processing → storage
2. **Auth boundary verification**: Ensure all protected routes check auth
3. **Secret detection**: Scan for hardcoded credentials, API keys, tokens
4. **Injection surfaces**: SQL, command, template injection across file boundaries
5. **OWASP Top 10 mapping**: Classify findings by OWASP category

### Architecture Review

Load: `Read("$\{CLAUDE_PLUGIN_ROOT\}/skills/audit-full/references/architecture-review-guide.md")` for the full guide.

Key analysis patterns:
1. **Dependency direction**: Verify imports flow inward (clean architecture)
2. **Circular dependencies**: Detect import cycles across modules
3. **Layer violations**: Business logic in controllers, DB in routes, etc.
4. **Pattern consistency**: Same problem solved differently across codebase
5. **Coupling analysis**: Count cross-module imports, identify tight coupling

### Dependency Audit

Load: `Read("$\{CLAUDE_PLUGIN_ROOT\}/skills/audit-full/references/dependency-audit-guide.md")` for the full guide.

Key analysis patterns:
1. **Known CVEs**: Check versions against known vulnerabilities
2. **License compliance**: Identify copyleft licenses in proprietary code
3. **Version currency**: Flag significantly outdated dependencies
4. **Transitive risk**: Identify deep dependency chains
5. **Unused dependencies**: Detect installed but never imported packages

### Progressive Output (CC 2.1.76)

Output findings **incrementally** as each audit mode completes — don't batch until the report:

1. **Security findings first** — show critical/high vulnerabilities immediately, don't wait for architecture review
2. **Architecture findings** — show dependency direction violations, circular deps as they surface
3. **Dependency findings** — show CVE matches, license compliance issues

For multi-mode audits (Full), each mode's findings appear as they complete. This lets users act on critical security findings while architecture analysis is still running.

---

## STEP 3.5: Adversarial Refutation (effort-gated)

Before the report, a separate **blind refuter** verifies CRITICAL/HIGH findings — the
structural fix for self-preferential bias (a single-context pass grading its own findings
anchors on its own reasoning). `low`/`medium` skip this step; `high` runs single advisory
refuters; `xhigh` runs the engine's quorum (3 for CRITICAL, 2 for HIGH).

Load the protocol + audit-full bindings: `Read("$\{CLAUDE_PLUGIN_ROOT\}/skills/audit-full/references/adversarial-refutation.md")`
(which loads the shared engine `$\{CLAUDE_PLUGIN_ROOT\}/shared/rules/adversarial-refutation.md`).

These refuters are audit-full's **only** sub-agent spawns (the producer is single-context),
always isolated `Agent(...)` with no `team_name`, fed only a neutral claim (category +
`file:line`). **Deterministic ground truth is exempt** — CVE/CVSS matches, failing build/test,
type errors are never refuted; only a *reachability claim* on top of a CVE is. Cross-file
findings the refuter can't reproduce from its narrow slice stay **UPHELD** (engine §5).
Refutation never silently drops a CRITICAL — the ledger (`refutation-ledger.json`) records
survived/killed/downgraded, and removing a CRITICAL/HIGH from the report needs user confirmation.

---

## STEP 4: Generate Report

Load the report template: `Read("$\{CLAUDE_PLUGIN_ROOT\}/skills/audit-full/assets/audit-report-template.md")`.

Report structure and severity classification: `Read("$\{CLAUDE_PLUGIN_ROOT\}/skills/audit-full/references/report-structure.md")` for finding table format, severity breakdown (CRITICAL/HIGH/MEDIUM/LOW with timelines), and architecture diagram conventions.

Severity matrix: `Read("$\{CLAUDE_PLUGIN_ROOT\}/skills/audit-full/assets/severity-matrix.md")` for classification criteria.

### Completion Checklist

Before finalizing the report, verify with `Read("$\{CLAUDE_PLUGIN_ROOT\}/skills/audit-full/checklists/audit-completion.md")`.

### PushNotification on Completion (CC 2.1.110+)

A full-codebase 1M-context audit typically runs 15–60 minutes on medium projects and can exceed that on large ones. **After the report file is written and the completion checklist passes, call `PushNotification`** so the finding counts are visible even if the user walked away.

```python
PushNotification(
  message=f"ork:audit-full complete — {SCOPE}: {critical}C/{high}H/{medium}M/{low}L · {report_path}",
  status="proactive"
)
```

Full rule: `Read("$\{CLAUDE_PLUGIN_ROOT\}/skills/chain-patterns/rules/push-notification-on-completion.md")`.

---

## When NOT to Use

| Situation | Use Instead |
|-----------|-------------|
| Small targeted check (1-5 files) | Direct Read + analysis |
| CI/CD automated scanning | `security-scanning` skill |
| Multi-agent graded verification | `/ork:verify` |
| Exploring unfamiliar codebase | `/ork:explore` |
| Codebase > 125K LOC (exceeds 1M) | **stay here** — STEP 1 routes to the map-reduce tier (`workflows/audit-full-mapreduce.js`); `/ork:verify` only if you want multi-agent *graded* verification instead of an audit |

---

## Notes for whole-codebase passes

> **Oversized reads (CC 2.1.144+):** When loading large files, Read returns a `[PARTIAL view]` truncated first page instead of a hard error if the whole-file read exceeds the token limit. Detect that notice and re-read with explicit `offset`/`limit` to page through the rest — a partial read silently omits code an audit must not miss.

> **When context fills (CC 2.1.141+):** Use the rewind menu's "Summarize up to here" to compress earlier turns while keeping recent findings, instead of restarting the audit. Reactive compaction (CC 2.1.142+) sizes the first summarize to the actual overflow, so a wasted second pass mid-turn is now rare.

---

## Running unattended with /goal

Set a completion condition with `/goal` (CC 2.1.139+) and this skill will keep working across turns until the condition is met. Works in interactive, `-p`, and Remote Control. The overlay panel shows live elapsed / turns / tokens.

**Example completion condition for this skill:**

```
/goal until findings.critical == 0 OR no_new_critical_for_3_turns, or stop after 30 turns
```

Stops when: zero critical issues remain across 3 consecutive passes, or a structural anti-pattern budget is reached. Compatible with claude.ai Remote Control runs.

---

## Related Skills

- `security-scanning` — Automated scanner integration (npm audit, Semgrep, etc.)
- `ork:security-patterns` — Security architecture patterns and OWASP vulnerability classification
- `ork:architecture-patterns` — Architectural pattern reference
- `ork:quality-gates` — Quality assessment criteria
- `ork:verify` — Multi-agent verification (fallback for codebases exceeding 1M context)

## References

Load on demand with `Read("$\{CLAUDE_PLUGIN_ROOT\}/skills/audit-full/references/&lt;file&gt;")`:
| File | Content |
|------|---------|
| `references/security-audit-guide.md` | Cross-file vulnerability patterns |
| `references/architecture-review-guide.md` | Pattern and coupling analysis |
| `references/dependency-audit-guide.md` | CVE, license, currency checks |
| `references/adversarial-refutation.md` | Blind-refuter bindings (STEP 3.5) — loads the shared engine |
| `references/token-estimation.md` | File type ratios and budget planning |
| `assets/audit-report-template.md` | Structured output format |
| `assets/severity-matrix.md` | Finding classification criteria |
| `checklists/audit-completion.md` | Pre-report verification |
| `scripts/estimate-tokens.sh` | Automated LOC to token estimation |
| `workflows/audit-full-mapreduce.js` | Scale tier — shard→audit→synthesize→refute for repos that exceed 1M context (run via the Workflow tool) |


---

## Rules (2)

### Classify audit findings by severity with evidence from actual code locations — HIGH


# Classify Findings by Severity with Evidence

## Why

Without evidence-backed severity classification, findings are either all "CRITICAL" (causing alert fatigue) or uniformly "MEDIUM" (hiding real risks). Both patterns erode trust in audit reports.

## Rule

Every finding must include:
1. Severity level (CRITICAL / HIGH / MEDIUM / LOW)
2. File path and line number
3. Code snippet showing the vulnerability
4. Exploitation scenario or impact statement
5. OWASP/CWE classification where applicable

## Incorrect — vague findings without evidence

```markdown
## Findings

| # | Severity | Finding |
|---|----------|---------|
| 1 | HIGH | SQL injection possible |
| 2 | MEDIUM | Auth might be missing |
| 3 | HIGH | Dependencies outdated |
```

**Problems:**
- No file paths — developer cannot locate the issue
- No code evidence — finding cannot be verified
- No exploitation scenario — severity is arbitrary
- "might be missing" is not a finding, it is speculation

## Correct — evidence-backed severity classification

```markdown
## Findings

| # | Severity | Category | File(s) | Finding |
|---|----------|----------|---------|---------|
| 1 | CRITICAL | Injection (CWE-89) | src/api/users.ts:42 | SQL injection via string interpolation |

### Finding 1: SQL Injection (CRITICAL)

**Location:** `src/api/users.ts:42`
**OWASP:** A05:2025 Injection | **CWE:** CWE-89

**Vulnerable code:**
  ```typescript
  const query = `SELECT * FROM users WHERE id = $\{req.params.id\}`;
  await db.execute(query);
  ```

**Exploitation:** Attacker sends `id=1; DROP TABLE users--` via
GET /api/users/:id. No parameterization or input validation exists
between the route handler (line 38) and the query execution (line 42).

**Remediation:**
  ```typescript
  const query = "SELECT * FROM users WHERE id = $1";
  await db.execute(query, [req.params.id]);
  ```
```

## Severity Classification Criteria

| Severity | Criteria | Example |
|----------|----------|---------|
| CRITICAL | Exploitable without auth, data loss/breach | SQL injection, RCE, auth bypass |
| HIGH | Exploitable with auth, significant impact | IDOR, privilege escalation, SSRF |
| MEDIUM | Requires specific conditions to exploit | CSRF, info disclosure, weak crypto |
| LOW | Minimal impact, defense-in-depth | Missing headers, verbose errors |


### Declare audit scope upfront before loading files to avoid context window exhaustion — HIGH


# Declare Audit Scope Before Loading

## Why

The 1M context window is large but finite. Loading every file without a scope declaration means generated code, test fixtures, and vendor files consume tokens that should go to critical source files.

## Rule

Before loading any files, produce a scope declaration that includes:
1. Audit mode (security / architecture / dependency / full)
2. Directory inclusion list
3. File exclusion patterns
4. Estimated token budget vs available budget

## Incorrect — audit everything without scoping

```markdown
## Audit Plan
1. Load all files in the repository
2. Analyze everything
3. Generate report
```

```bash
# Loads everything including generated files
find . -name "*.ts" -o -name "*.js" | xargs cat
```

**Problems:**
- Generated files (`dist/`, `plugins/`) consume 40%+ of context
- Test fixtures and snapshots add noise
- No priority ordering means entry points may be truncated

## Correct — declare scope with budget allocation

```markdown
## Audit Scope Declaration

**Mode:** Security audit
**Target directories:** src/api/, src/auth/, src/middleware/
**Exclusions:** dist/, node_modules/, *.test.ts, *.spec.ts, __snapshots__/
**Token budget:** ~950K available (1M GA), estimated usage: ~85K (9%)
**Priority order:**
  1. Entry points (src/index.ts, src/app.ts)
  2. Auth boundary (src/auth/*, src/middleware/auth*)
  3. Data access layer (src/db/*, src/repositories/*)
  4. API routes (src/api/*)
```

```bash
# Scoped file discovery with exclusions
find src/api src/auth src/middleware \
  -name "*.ts" \
  ! -name "*.test.ts" \
  ! -name "*.spec.ts" \
  ! -path "*/__snapshots__/*"
```

## Checklist

| Check | Required |
|-------|----------|
| Audit mode declared | Yes |
| Target directories listed | Yes |
| Exclusion patterns defined | Yes |
| Token budget estimated | Yes |
| Priority loading order set | Yes |



---

## References (8)

### Adversarial Refutation

# Adversarial Refutation — audit-full bindings

Thin adapter. Loads the shared engine, then binds it to audit-full's severity-ranked findings.

**Load the engine first:** `Read("$\{CLAUDE_PLUGIN_ROOT\}/shared/rules/adversarial-refutation.md")`
— the blindness contract, independent-score-first, citation-verify, quorum, cross-file
UPHELD-default, deterministic-exemption, no-auto-flip, spawn-ceiling, ledger schema, and
isolated-spawn rules. This file only supplies what's audit-full-specific.

## Bindings

| Engine concept | audit-full binding |
|----------------|--------------------|
| "finding" | a severity-ranked finding from STEP 3 (Security / Architecture / Dependency), tagged CRITICAL/HIGH/MEDIUM/LOW |
| rubric | the relevant STEP-3 guide (`security-audit-guide.md` / `architecture-review-guide.md` / `dependency-audit-guide.md`) + `assets/severity-matrix.md` |
| refuter agent | a blind `Agent(...)` chosen by finding domain — `security-auditor` (security), `backend-system-architect` (architecture), `code-quality-reviewer` (dependency/other). **audit-full's producer is single-context Opus, so these refuters are its ONLY sub-agent spawns** |
| code artifact | the cited `file:line` slice — the refuter re-reads it from the codebase itself (it does NOT get the whole-codebase context the producer had, so cross-file findings follow engine §5 UPHELD-default) |
| ledger | `refutation-ledger.json` in the audit job dir (`$CLAUDE_JOB_DIR`) |
| revised output | a "Refuted?" column on the STEP 4 finding table + `refuted` / `original_severity` fields; severity changes honor **no-auto-flip** (§7) |

## Scope filter (which findings get a refuter)

A finding qualifies only if decision-bearing — ANY of:
- **CRITICAL** or **HIGH** severity (these drive the report's headline + remediation timeline)
- a finding that asserts **exploitability/reachability** (a claim, not a tool match)

Skip: MEDIUM/LOW informational findings, and **deterministic ground truth** — a CVE/CVSS match
from a dependency scan, a failing build/test, a type error (engine §6). Only a *reachability
claim* layered on top of a CVE ("this CVE is exploitable because input reaches it") is
refutable, and only that claim. Dedup to root-cause BEFORE counting; respect the global spawn
ceiling (default 24, engine §8) — rank by `severity × distance-from-decision-boundary` and
flag any un-refuted overflow "manual review required".

## Cross-file caution (audit-full-specific)

audit-full's edge is whole-codebase cross-file reasoning (taint flows, auth-boundary gaps
spanning modules). A refuter only gets the cited slice, so per engine §5 a "could not
reproduce the traced flow" result is **UPHELD, never REFUTED** — the card MUST carry the
producer's full traced file set so the refuter knows what it's missing. A narrow-context
refuter must never kill a true cross-file finding it simply couldn't see.

## Effort gate (audit-full-specific)

audit-full is already a heavy single-context pass; keep refutation bounded:
- `low` / `medium` → **skip STEP 3.5 entirely**
- `high` → up-to-ceiling **single** refuters on CRITICAL/HIGH, **advisory only** (surfaced, not
  auto-applied; a single refuter never demotes a CRITICAL on its own — §7)
- `xhigh` → **quorum** (§4): 3-refuter majority for CRITICAL, 2 for HIGH; a kill that would drop
  a CRITICAL from the report requires explicit user confirmation (§7)

## Isolation note

Refuters are ALWAYS standalone `Agent(...)` Task spawns with **no `team_name`**, fed only the
serialized claim (category + `file:line`, NO producer severity/prose). audit-full has no mesh
to leak into, but the rule holds: delivery is prompt/`additionalContext`-only (engine §9).


### Architecture Review Guide

# Architecture Review Guide

Pattern consistency, coupling analysis, and structural health assessment.

## Dependency Direction Analysis

### Clean Architecture Layers

```
┌─────────────────────────────┐
│  Presentation (routes, UI)  │  ← Outermost
├─────────────────────────────┤
│  Application (use cases)    │
├─────────────────────────────┤
│  Domain (entities, rules)   │
├─────────────────────────────┤
│  Infrastructure (DB, APIs)  │  ← Outermost
└─────────────────────────────┘

Rule: Dependencies point INWARD only.
Violation: Domain importing from Infrastructure.
```

### Detection Method

1. Map each file to a layer based on directory structure
2. Parse imports/requires in each file
3. Flag imports that point outward (wrong direction)

```
# VIOLATION EXAMPLE:
# src/domain/user.ts imports from src/infrastructure/db.ts
import { dbPool } from '../infrastructure/db'  // Wrong direction!

# CORRECT:
# src/domain/user.ts defines interface
# src/infrastructure/db.ts implements it
```

## Circular Dependency Detection

### What to Look For

```
# File A imports File B, File B imports File A
// src/auth/service.ts
import { UserRepo } from '../users/repo'

// src/users/repo.ts
import { AuthService } from '../auth/service'  // Circular!
```

### Resolution Patterns

| Pattern | When to Use |
|---------|-------------|
| Extract interface | Both modules depend on abstraction |
| Merge modules | Modules are conceptually one unit |
| Event-based | Decouple with pub/sub or event emitter |
| Dependency injection | Inject at runtime, not import time |

## Pattern Consistency Check

Look for the same problem solved differently across the codebase:

| Area | Inconsistency Example |
|------|----------------------|
| Error handling | Some files throw, others return Result, others use callbacks |
| Validation | Zod in some files, Joi in others, manual checks elsewhere |
| Data access | Raw SQL in some, ORM in others, mixed in same file |
| Logging | console.log, winston, pino, custom logger all present |
| Config | env vars, config files, hardcoded, mixed approaches |
| HTTP clients | fetch, axios, got, node-fetch all imported |

### Scoring

| Consistency | Score |
|-------------|-------|
| Single pattern everywhere | 10/10 |
| Primary + 1 legacy pattern | 7/10 |
| 2-3 competing patterns | 4/10 |
| No discernible pattern | 1/10 |

## Coupling Analysis

### Metrics to Calculate

| Metric | Formula | Healthy Range |
|--------|---------|---------------|
| Afferent coupling (Ca) | Modules that depend ON this module | &lt; 10 |
| Efferent coupling (Ce) | Modules this module depends ON | &lt; 8 |
| Instability (I) | Ce / (Ca + Ce) | Varies by layer |
| Abstractness (A) | Interfaces / Total types | > 0.3 for core |

### Module Boundary Health

```
# Count imports between directories:
src/auth/ → src/users/    : 5 imports (acceptable)
src/auth/ → src/payments/  : 12 imports (high coupling!)
src/utils/ → src/auth/     : 0 imports (good, utils is generic)
```

### Red Flags

- Module with > 15 external dependents (God module)
- Utility file with > 500 lines (needs splitting)
- Circular import chains > 2 files deep
- Config/env imported in > 20 files (use DI instead)

## Layering Violations

| Violation | Example | Fix |
|-----------|---------|-----|
| DB in route handler | `router.get('/', async (req, res) => \{ db.query(...) \})` | Extract to service layer |
| Business logic in middleware | Auth middleware doing role-based access with complex rules | Move to use-case layer |
| HTTP in domain | Domain entity calling external API | Inject via port/adapter |
| UI logic in API | API returning HTML-formatted strings | Return data, format in frontend |

## Architecture Diagram Output

Generate ASCII diagram showing module dependencies:

```
┌──────────┐     ┌──────────┐     ┌──────────┐
│  routes   │────▶│ services │────▶│  repos   │
└──────────┘     └──────────┘     └──────────┘
      │                │                │
      ▼                ▼                ▼
┌──────────┐     ┌──────────┐     ┌──────────┐
│middleware│     │  domain  │     │    db     │
└──────────┘     └──────────┘     └──────────┘

Legend: ──▶ = imports from
Violations marked with ✗
```


### Audit Scope Dialog

# Audit Scope Dialog

## STEP 0: Verify User Intent with AskUserQuestion

**BEFORE creating tasks**, clarify audit scope:

```python
AskUserQuestion(
  questions=[
    {
      "question": "What type of audit do you want to run?",
      "header": "Audit mode",
      # multiSelect questions do not render previews (single-select only) — text-only
      "options": [
        {"label": "Full audit (Recommended)", "description": "Security + architecture + dependencies in one pass (Opus 1M context, all files at once)"},
        {"label": "Security audit", "description": "Cross-file vulnerability analysis, data flow tracing, OWASP mapping, secret detection"},
        {"label": "Architecture review", "description": "Pattern consistency, coupling metrics, dependency violations, layer enforcement"},
        {"label": "Dependency audit", "description": "CVE scan, license compliance, version drift, unused/transitive-risk deps"}
      ],
      "multiSelect": true
    },
    {
      "question": "What should be audited?",
      "header": "Scope",
      "options": [
        {"label": "Entire codebase", "description": "Load all source files into context"},
        {"label": "Specific directory", "description": "Focus on a subdirectory (e.g., src/api/)"},
        {"label": "Changed files only", "description": "Audit only files changed vs main branch"}
      ],
      "multiSelect": false
    }
  ]
)
```

**Based on answers, adjust workflow:**
- **Full audit**: All 3 domains, maximum context usage
- **Security only**: Focus token budget on source + config files
- **Architecture only**: Focus on module boundaries, imports, interfaces
- **Dependency only**: Focus on lock files, manifests, import maps
- **Changed files only**: Use `git diff --name-only main...HEAD` to scope


### Dependency Audit Guide

# Dependency Audit Guide

License compliance, CVE checking, and version currency analysis.

## CVE Checking

### Automated Scanners

```bash
# JavaScript/TypeScript
npm audit --json
npx better-npm-audit audit

# Python
pip-audit --format=json
safety check --json

# Go
govulncheck ./...

# Rust
cargo audit
```

### Manual CVE Check

For dependencies without scanner coverage:
1. Check version in `package.json` / `pyproject.toml` / `go.mod`
2. Search [NVD](https://nvd.nist.gov/) or [OSV](https://osv.dev/) for package name
3. Compare installed version against affected version ranges
4. Classify by CVSS score

| CVSS Score | Severity | Action |
|-----------|----------|--------|
| 9.0-10.0 | CRITICAL | Update immediately |
| 7.0-8.9 | HIGH | Update within 1 week |
| 4.0-6.9 | MEDIUM | Update within 1 month |
| 0.1-3.9 | LOW | Track in backlog |

## License Compliance

### License Risk Tiers

| Tier | Licenses | Risk in Proprietary Code |
|------|----------|--------------------------|
| Permissive | MIT, BSD-2, BSD-3, ISC, Apache-2.0 | Safe |
| Weak copyleft | LGPL-2.1, LGPL-3.0, MPL-2.0 | Safe if dynamically linked |
| Strong copyleft | GPL-2.0, GPL-3.0, AGPL-3.0 | Requires source disclosure |
| Unknown | UNLICENSED, custom | Review manually |

### Detection Method

```bash
# JavaScript
npx license-checker --json --production

# Python
pip-licenses --format=json --with-urls

# Check for problematic licenses
npx license-checker --failOn "GPL-2.0;GPL-3.0;AGPL-3.0"
```

### What to Flag

- Any GPL/AGPL dependency in proprietary codebase → CRITICAL
- UNLICENSED dependencies → HIGH (legal risk)
- Dependencies with no license file → MEDIUM
- License changed between versions → LOW (track)

## Version Currency

### Currency Classification

| Status | Definition | Example |
|--------|-----------|---------|
| Current | Within 1 minor version of latest | react 19.1 when 19.2 is latest |
| Stale | 1+ major version behind | react 18.x when 19.x is latest |
| Outdated | 2+ major versions behind | react 17.x when 19.x is latest |
| EOL | No longer maintained | moment.js, request |

### High-Risk Outdated Patterns

| Pattern | Risk |
|---------|------|
| Framework 2+ majors behind | Missing security patches |
| Auth library outdated | Known vulnerabilities |
| TLS/crypto library outdated | Weak algorithms |
| ORM/DB driver outdated | SQL injection patches missing |

## Transitive Dependency Risk

### Deep Chains

```
your-app
  └── package-a@1.0.0
       └── package-b@2.0.0
            └── package-c@3.0.0  ← vulnerability here
```

**Risk**: You don't control `package-c`, and updating `package-a` may not update it.

### Detection

```bash
# Show dependency tree
npm ls --all --json | jq '.dependencies'

# Find deep chains (>4 levels)
npm ls --all 2>/dev/null | grep -E "^.{16,}" | head -20
```

### Mitigation

| Strategy | When |
|----------|------|
| `overrides` (npm) / `resolutions` (yarn) | Force specific version |
| Replace parent package | If parent is unmaintained |
| Vendor and patch | Last resort for critical fixes |

## Unused Dependencies

### Detection

```bash
# JavaScript
npx depcheck

# Python
pip-extra-reqs --ignore-module=tests .
```

### What to Flag

- Installed but never imported → MEDIUM (bloat, attack surface)
- Dev dependency in production deps → LOW (no runtime risk)
- Multiple packages for same purpose → LOW (e.g., both lodash and underscore)


### Report Structure

# Audit Report Structure

## Report Format

```markdown
# Audit Report: {project-name}
**Date:** {date} | **Mode:** {mode} | **Files loaded:** {count} | **LOC:** {loc}

## Executive Summary
{1-3 sentences: overall health, critical findings count}

## Findings

| # | Severity | Category | File(s) | Finding | Remediation |
|---|----------|----------|---------|---------|-------------|
| 1 | CRITICAL | Security | src/auth.ts:42 | ... | ... |

## Severity Breakdown
- CRITICAL: {n} (must fix before deploy)
- HIGH: {n} (fix within sprint)
- MEDIUM: {n} (fix within quarter)
- LOW: {n} (track and address)

## Architecture Diagram
{ASCII diagram of module dependencies}

## Recommendations
{Prioritized action items}
```

## Severity Classification

| Level | Criteria | Timeline |
|-------|----------|----------|
| CRITICAL | Exploitable vulnerability, data loss risk, auth bypass | Must fix before deploy |
| HIGH | Security weakness, major arch violation, EOL dependency | Fix within sprint |
| MEDIUM | Code smell, minor arch inconsistency, stale dependency | Fix within quarter |
| LOW | Style issue, minor improvement, documentation gap | Track and address |

## Codebase Loading Strategy

1. **Glob all source files** matching inclusion patterns
2. **Sort by priority**: entry points -> core modules -> utilities -> config
3. **Read files in parallel** using multiple Read tool calls per message
4. **Track loaded tokens** to stay within budget

### Inclusion Patterns (by language)

```bash
# TypeScript/JavaScript
**/*.ts **/*.tsx **/*.js **/*.jsx
**/package.json **/tsconfig.json

# Python
**/*.py
**/pyproject.toml **/setup.cfg **/requirements*.txt

# Config
**/.env.example **/docker-compose*.yml **/Dockerfile
**/*.yaml **/*.yml (non-lock)
```

### Reading Pattern

Read files in batches of 10-15 per message for efficiency:

```python
# Batch 1: Entry points and config
Read("src/index.ts")
Read("src/app.ts")
Read("package.json")
Read("tsconfig.json")
# ... up to 15 files

# Batch 2: Core modules
Read("src/api/routes.ts")
Read("src/db/connection.ts")
# ... next batch
```


### Security Audit Guide

# Security Audit Guide

Cross-file vulnerability analysis patterns for whole-codebase audits.

## Data Flow Tracing

Trace user input from entry to storage across file boundaries:

```
Entry Point → Validation → Processing → Storage
(route.ts)    (middleware)   (service.ts)  (repo.ts)
```

### What to Check at Each Stage

| Stage | Check | Severity if Missing |
|-------|-------|-------------------|
| Entry | Input validation, type coercion | HIGH |
| Validation | Schema validation, sanitization | CRITICAL |
| Processing | Business logic auth checks | HIGH |
| Storage | Parameterized queries, encoding | CRITICAL |

## Cross-File Vulnerability Patterns

### 1. Auth Bypass via Missing Middleware

```
# PATTERN: Route defined without auth middleware
router.get('/admin/users', getUsersHandler)  # No authMiddleware!

# Compare against protected routes:
router.get('/admin/settings', authMiddleware, getSettingsHandler)
```

**Detection**: Glob all route files, check each handler has auth middleware.

### 2. SQL Injection via String Interpolation

```
# PATTERN: Variable in SQL string (any file)
query(`SELECT * FROM users WHERE id = '${userId}'`)

# Safe pattern:
query('SELECT * FROM users WHERE id = $1', [userId])
```

**Detection**: Grep for template literals containing SQL keywords.

### 3. Command Injection via Shell Exec

```
# PATTERN: User input in exec/spawn
exec(`git log --author="${username}"`)

# Safe pattern:
execFile('git', ['log', `--author=${username}`])
```

**Detection**: Grep for `exec(`, `execSync(`, `spawn(` with template literals.

### 4. Secret Leakage

```
# PATTERN: Hardcoded secrets
const API_KEY = 'sk-live-abc123...'
const password = 'admin123'

# PATTERN: Secrets in error messages
throw new Error(`Auth failed for ${password}`)

# PATTERN: Secrets in logs
console.log(`Connecting with key: ${apiKey}`)
```

**Detection**: Grep for common secret patterns (`sk-`, `ghp_`, `Bearer `, password assignments).

### 5. SSRF via Unvalidated URLs

```
# PATTERN: User-controlled URL in fetch/axios
const response = await fetch(req.body.url)

# Safe pattern:
const url = new URL(req.body.url)
if (!ALLOWED_HOSTS.includes(url.hostname)) throw new Error('Blocked')
```

### 6. Path Traversal

```
# PATTERN: User input in file path
const filePath = path.join(uploadDir, req.params.filename)
// filename could be '../../etc/passwd'

# Safe pattern:
const resolved = path.resolve(uploadDir, req.params.filename)
if (!resolved.startsWith(uploadDir)) throw new Error('Blocked')
```

## OWASP Top 10 Mapping

| OWASP | What to Look For |
|-------|-----------------|
| A01 Broken Access Control | Missing auth middleware, IDOR, privilege escalation |
| A02 Cryptographic Failures | Weak hashing, HTTP for sensitive data, hardcoded keys |
| A03 Injection | SQL, command, template injection across boundaries |
| A04 Insecure Design | Missing rate limiting, no abuse prevention |
| A05 Security Misconfiguration | Debug mode in prod, default credentials, CORS * |
| A06 Vulnerable Components | Outdated deps with known CVEs |
| A07 Auth Failures | Weak passwords, no MFA, session fixation |
| A08 Data Integrity | Unsigned updates, CI/CD without verification |
| A09 Logging Failures | Missing audit logs, secrets in logs |
| A10 SSRF | Unvalidated URLs in server-side requests |

## Severity Classification

| Severity | Criteria |
|----------|----------|
| CRITICAL | Exploitable without authentication, data breach risk |
| HIGH | Exploitable with low-privilege access, system compromise |
| MEDIUM | Requires specific conditions, limited impact |
| LOW | Informational, defense-in-depth improvement |


### Token Budget Planning

# Token Budget Planning

## Run Token Estimation

```bash
# Use the estimation script
bash ${CLAUDE_PLUGIN_ROOT}/skills/audit-full/scripts/estimate-tokens.sh /path/to/project
```

## Manual Estimation Rules

| File Type | Tokens per Line (approx) |
|-----------|-------------------------|
| TypeScript/JavaScript | ~8 tokens/line |
| Python | ~7 tokens/line |
| JSON/YAML config | ~5 tokens/line |
| Markdown docs | ~6 tokens/line |
| CSS/SCSS | ~6 tokens/line |

## Budget Allocation

| Context Size | Available for Code | Fits LOC (approx) |
|-------------|-------------------|-------------------|
| 200K | ~150K tokens | ~20K LOC |
| 1M (standard) | ~950K tokens | ~125K LOC |

## Auto-Exclusion List

Always exclude from loading:
- `node_modules/`, `vendor/`, `.venv/`, `__pycache__/`
- `dist/`, `build/`, `.next/`, `out/`
- `*.min.js`, `*.map`, `*.lock` (read lock files separately for deps audit)
- Binary files, images, fonts
- Test fixtures and snapshots (unless auditing tests)
- Generated files (protobuf, graphql codegen)

## If Codebase Exceeds Budget

audit-full owns this case now — it does **not** punt. The map-reduce tier
(`workflows/audit-full-mapreduce.js`, run via the Workflow tool) shards the repo,
audits each shard in its own context, then recovers cross-shard edges in a synthesis
pass. Prefer it over narrowing scope (which silently drops coverage).

1. **Map-reduce tier (recommended)**: run the workflow with shards derived from the estimate — full coverage, cross-shard boundary pass, same STEP 3.5 refutation.
2. **Directory scoping**: narrow to specific directories — fast but **drops coverage** outside the scope; say so.
3. **Priority loading**: entry points + critical paths only — triage, not a full audit.
4. **`/ork:verify`**: only if you actually want multi-agent *graded* verification rather than an audit.

```python
# Over-budget routing
AskUserQuestion(
  questions=[{
    "question": "Codebase exceeds the single-context budget. How to proceed?",
    "header": "Too large",
    "options": [
      {"label": "Map-reduce audit (full coverage)", "description": "Shard → per-shard audit → cross-shard synthesis → refute (workflows/audit-full-mapreduce.js)"},
      {"label": "Narrow scope", "description": "Audit specific directories only — drops coverage elsewhere"},
      {"label": "Priority loading", "description": "Entry points + critical paths only (triage)"}
    ],
    "multiSelect": false
  }]
)
```


### Token Estimation

# Token Estimation Guide

Planning context budget for whole-codebase loading.

## Token Ratios by File Type

| File Type | Tokens/Line | Tokens/KB | Notes |
|-----------|-------------|-----------|-------|
| TypeScript/JavaScript | ~8 | ~320 | Variable names inflate count |
| Python | ~7 | ~280 | Indentation is efficient |
| Go | ~7 | ~280 | Verbose but predictable |
| JSON | ~5 | ~200 | High repetition, low entropy |
| YAML | ~5 | ~200 | Similar to JSON |
| Markdown | ~6 | ~240 | Prose-heavy content |
| CSS/SCSS | ~6 | ~240 | Property-value pairs |
| SQL | ~6 | ~240 | Keyword-heavy |
| HTML/JSX | ~9 | ~360 | Attribute-heavy markup |
| Protobuf/GraphQL schema | ~5 | ~200 | Declarative, repetitive |

## Quick Estimation Formula

```
Total tokens ≈ Total LOC × 7.5 (average)
```

For more precision:
```
Total tokens ≈ (TS lines × 8) + (Py lines × 7) + (Config lines × 5) + (Other × 7)
```

## Context Budget Planning

| Context Size | Total | Reserved for Prompt | Available for Code | Max LOC |
|-------------|-------|--------------------|--------------------|---------|
| 1M (standard) | 1,000,000 | ~50,000 | ~950,000 | ~125,000 |
| 200K (legacy) | 200,000 | ~50,000 | ~150,000 | ~20,000 |

**Reserved for prompt** includes: system prompt, skill content, analysis instructions, and output space.

## Exclusion Priority

When codebase exceeds budget, exclude in this order:

1. **Always exclude**: `node_modules/`, `vendor/`, `.venv/`, `dist/`, `build/`, `.next/`
2. **Exclude first**: Test fixtures, snapshots, migration files, generated code
3. **Exclude second**: Test files (unless auditing test quality)
4. **Exclude third**: Documentation, README files
5. **Keep last**: Source files, config, entry points

## Loading Priority

When partially loading, prioritize in this order:

1. **Entry points**: `index.ts`, `main.py`, `app.ts`, `server.ts`
2. **Route definitions**: API routes, page routes
3. **Middleware/interceptors**: Auth, validation, error handling
4. **Business logic**: Services, use cases, domain models
5. **Data access**: Repositories, ORM models, migrations
6. **Config**: Environment config, feature flags, secrets management
7. **Utilities**: Shared helpers, common functions

## Real-World Sizing Examples

| Project Type | Typical LOC | Estimated Tokens | Fits in |
|-------------|-------------|-----------------|---------|
| Microservice | 5-15K | 40-120K | 1M (single-pass) |
| Small app | 15-30K | 120-240K | 1M (single-pass) |
| Medium app | 30-60K | 240-480K | 1M (single-pass) |
| Large app | 60-125K | 480K-950K | 1M (fits with scoping) |
| Large monolith | 125K+ | 950K+ | Directory-scoped or /ork:verify |



---

## Checklists (1)

### Audit Completion

# Audit Completion Checklist

Verify before finalizing the audit report.

## Pre-Report Verification

### Coverage

- [ ] All source files in scope were loaded (check file count vs glob count)
- [ ] Entry points identified and traced
- [ ] Configuration files reviewed (env, docker, CI)
- [ ] Lock files checked (package-lock.json, poetry.lock, go.sum)

### Security (if applicable)

- [ ] All public endpoints checked for auth middleware
- [ ] Data flow traced from input → storage for at least 3 critical paths
- [ ] Secret detection scan completed (grep for API keys, passwords, tokens)
- [ ] OWASP Top 10 categories all considered (mark N/A if not applicable)
- [ ] Third-party integrations checked for SSRF risk
- [ ] File upload/download paths checked for traversal

### Architecture (if applicable)

- [ ] Dependency direction verified (imports flow inward)
- [ ] Circular dependencies checked
- [ ] Pattern consistency evaluated (error handling, validation, data access)
- [ ] Module coupling analyzed (cross-directory import counts)
- [ ] Layer violations identified
- [ ] ASCII architecture diagram generated

### Dependencies (if applicable)

- [ ] `npm audit` / `pip-audit` / equivalent run
- [ ] License compliance checked (no GPL in proprietary)
- [ ] Outdated packages identified with severity
- [ ] Unused dependencies flagged
- [ ] Transitive dependency risks assessed

### Report Quality

- [ ] Every finding has specific file:line references
- [ ] Every finding has a remediation suggestion with code
- [ ] Severity classifications match the severity matrix
- [ ] No duplicate findings (same root cause reported once)
- [ ] False positives verified and removed
- [ ] Recommendations prioritized by impact and effort
- [ ] Executive summary accurately reflects findings
- [ ] Health score calculated correctly

### Completeness

- [ ] All selected audit modes completed
- [ ] Context utilization reported (tokens used / available)
- [ ] Files list in appendix matches loaded files
- [ ] Report follows the template structure