audit

name	audit
description	Full codebase audit using Agent Teams. Sets scope=full and depth=deep (by default), then delegates to the shared Roundtable Circle orchestration phases. Summons up to 7 built-in Ashes (custom Ashes wired in orchestration layer in v3.x). Optional `--deep` runs multi-wave investigation with deep Ashes. Phase 0.45 context building spawns context-builder agent to map trust boundaries, invariants, and state flows before vulnerability hunting (auto for deep). Supports `--focus` for targeted audits. Supports `--incremental` for stateful, prioritized batch auditing with 3-tier coverage tracking (file, workflow, API) and session-persistent audit history.
user-invocable	true
disable-model-invocation	false
argument-hint	[--deep] [--focus <area>] [--max-agents <N>] [--dry-run] [--no-lore] [--deep-lore] [--standard] [--incremental] [--resume] [--status] [--reset] [--tier <file|workflow|api|all>] [--force-files <glob>] [--dirs <path,...>] [--exclude-dirs <path,...>] [--prompt <text>] [--prompt-file <path>]
allowed-tools	["Agent","TaskCreate","TaskList","TaskUpdate","TaskGet","TeamCreate","TeamDelete","SendMessage","Read","Write","Bash","Glob","Grep","AskUserQuestion"]

Runtime context (preprocessor snapshot):

• Active workflows: !find tmp -maxdepth 1 -name '.rune-*-*.json' -exec grep -l '"running"' {} + 2>/dev/null | wc -l | tr -d ' '
• Current branch: !git branch --show-current 2>/dev/null || echo "n/a"

/rune:audit — Full Codebase Audit

Thin wrapper that sets audit-specific parameters, then delegates to the shared Roundtable Circle orchestration. Unlike /rune:appraise (which reviews changed files via git diff), /rune:audit scans the entire project.

Load skills: roundtable-circle, context-weaving, rune-orchestration, team-sdk

Flags

Flag	Description	Default
--focus <area>	Limit audit to specific area: security, performance, quality, frontend, docs, backend, full	full
--max-agents <N>	Cap maximum Ash summoned (1-8, including custom)	All selected
--dry-run	Show scope selection and Ash plan without summoning agents	Off
--no-lore	Disable Phase 0.5 Lore Layer (git history risk scoring)	Off
--deep-lore	Run Lore Layer on ALL files (default: Tier 1 only)	Off
--deep	Run multi-wave deep audit with deep investigation Ashes	On (default for audit)
--standard	Override default deep mode — run single-wave standard audit	Off
--incremental	Enable incremental stateful audit — prioritized batch selection with persistent audit history	Off
--resume	Resume interrupted incremental audit from checkpoint	Off
--status	Show coverage report only (no audit performed)	Off
--reset	Reset incremental audit history and start fresh	Off
--tier <tier>	Limit incremental audit to specific tier: file, workflow, api, all	all
--force-files <glob>	Force specific files into incremental batch regardless of priority score	None
--dirs <path,...>	Comma-separated list of directories to audit (relative to project root).	All dirs (full scan)
--exclude-dirs <path,...>	Comma-separated list of directories to exclude from audit.	None
--prompt <text>	Inline custom inspection criteria injected into every Ash prompt. Sanitized via sanitizePromptContent(). Findings use standard prefixes with source="custom" attribute.	None
--prompt-file <path>	Path to a Markdown file containing custom inspection criteria. Loaded, sanitized, and injected into Ash prompts. Takes precedence over --prompt when both are set. See prompt-audit.md.	None

Note: Unlike /rune:appraise, there is no --partial flag. Audit always scans the full project.

Flag interactions: --dirs and --exclude-dirs are pre-filters on the Phase 0 find command — they narrow the all_files set before it reaches Rune Gaze, the incremental layer, or the Lore Layer (those components receive a smaller array and require zero changes). --dirs and --exclude-dirs can be combined; --exclude-dirs is applied after --dirs (intersection then exclusion). --incremental and --deep are orthogonal. --incremental --deep runs incremental file selection (batch) followed by deep investigation Ashes on the selected batch. --incremental --focus applies focus filtering BEFORE priority scoring (reduces candidate set, then scores within that set).

Focus mode selects only the relevant Ash (see circle-registry.md for the mapping).

Max agents reduces team size when context or cost is a concern. Priority order: Ward Sentinel > Forge Warden > Veil Piercer > Pattern Weaver > Glyph Scribe > Knowledge Keeper.

Conditional Ashes (not counted in the 7 built-in cap — spawned only when gate conditions are met):

• flow-integrity-tracer (FLOW- prefix): Data flow integrity verification across UI↔API↔DB layers. Gate: 2+ stack layers detected in scanned files. (v3.x: data_flow is unconditional.) See circle-registry.md for the full conditional Ash registry.

Preamble: Set Parameters

// Parse depth: audit defaults to deep (unlike appraise which defaults to standard)
// v3.x: always_deep removed as user-tunable; --deep flag is the canonical control
const depth = flags['--standard']
  ? "standard"
  : (flags['--deep'] !== false)
    ? "deep"
    : "standard"

const audit_id = Bash(`date +%Y%m%d-%H%M%S`).trim()
const isIncremental = flags['--incremental'] === true
let incrementalLockAcquired = false  // Tracks whether THIS session owns the lock (Finding 1/2 fix)
const sessionId = "${CLAUDE_SESSION_ID}" || Bash(`echo "\${RUNE_SESSION_ID:-}"`).trim()  // Standalone variable for use in state writes (Finding 3 fix)

Workflow Lock (reader)

const lockConflicts = Bash(`cd "${CWD}" && source plugins/rune/scripts/lib/workflow-lock.sh && rune_check_conflicts "reader"`)
if (lockConflicts.includes("CONFLICT")) {
  AskUserQuestion({ question: `Active workflow conflict:\n${lockConflicts}\nProceed anyway?` })
} else if (lockConflicts.includes("ADVISORY")) {
  // ADVISORY = reader/planner + writer coexistence (see workflow-lock.sh compatibility matrix)
  const sanitizedConflicts = lockConflicts.replace(/[<>&"']/g, '')
  log(`Other workflow(s) detected in separate session(s):\n${sanitizedConflicts}\nCross-session concurrency is supported — proceeding normally.`)
}
Bash(`cd "${CWD}" && source plugins/rune/scripts/lib/workflow-lock.sh && rune_acquire_lock "audit" "reader"`)

Phase 0: Pre-flight

Directory scope resolution for --dirs and --exclude-dirs flags. Validates paths (SEC: rejects traversal, absolute escape), normalizes, deduplicates, verifies existence, and records dir_scope metadata for downstream phases. Then scans project files via find (excluding .git, node_modules, dist, etc.).

See phase-0-dir-scope.md for the full pseudocode (7-step validation + file scan).

Phase 0.1-0.4: Incremental Layer (conditional)

Gate: Only runs when isIncremental === true. When --incremental is NOT set, these phases are skipped entirely with zero overhead — the full all_files list passes directly to Phase 0.5.

See incremental-phases.md for the full Phase 0.0-0.4 pseudocode (8 sub-phases: Status-Only Exit, Reset, Lock Acquire, Resume Check, Build Manifest, Manifest Diff, Priority Scoring, Batch Selection).

Tier 2/3 integration: See workflow-discovery.md and workflow-audit.md for Tier 2 (cross-file workflow) execution details. See api-discovery.md and api-audit.md for Tier 3 (endpoint contract) execution details.

Load Custom Ashes

In v3.x, custom Ashes are wired in the orchestration layer rather than configured. See custom-ashes.md for the wiring contract; defaults (max_ashes, defaults.disable_ashes) live in v3-defaults.md.

Phase 0.45: Context Building (conditional)

Spawn context-builder research agent to build architectural understanding before vulnerability hunting. Produces a structured context map injected into every Ash's spawn prompt.

Gate: Hardcoded "auto" in v3.x (see v3-defaults.md): runs for --deep audits only.

// v3.x: audit context-building hardcoded to "auto".
const contextBuilding = "auto"
const contextTimeout = 300 * 1000  // seconds → ms

const shouldBuildContext =
  contextBuilding === "always" ||
  (contextBuilding === "auto" && depth === "deep")

if (shouldBuildContext) {
  const contextOutputPath = `${outputDir}context-map.md`

  // Create task for context-builder
  TaskCreate({
    subject: "Build audit context map",
    description: `Analyze codebase architecture: entry points, trust boundaries, invariants, state flows. Write to ${contextOutputPath}. Budget: ${contextTimeout / 1000}s.`
  })

  // Spawn context-builder on the audit team
  Agent({
    prompt: `Build a structured context map for this codebase audit.
Output path: ${contextOutputPath}
Scope: ${all_files.length} files in project.
Team: ${teamName}. Claim your task via TaskList.`,
    subagent_type: "rune:research:context-builder",
    team_name: teamName,
    name: "context-builder",
    model: "sonnet"
  })

  // Wait with timeout (non-blocking — proceed without context on timeout)
  const cbResult = waitForCompletion(teamName, 1, {
    timeoutMs: contextTimeout,
    pollIntervalMs: 30_000,
    label: "Context Building"
  })

  // Read context map if produced
  let sharedAuditContext = ""
  try {
    const contextMap = Read(contextOutputPath)
    if (contextMap && contextMap.trim().length > 100) {
      sharedAuditContext = `\n## Shared Audit Context\n\nThe following context map was generated by pre-analysis. Use it to understand the system architecture, trust boundaries, and invariants before reviewing code.\n\n${contextMap}\n`
      log(`Context map loaded: ${contextMap.split("\n").length} lines`)
    }
  } catch (e) {
    log("Context map not available — proceeding without shared context")
  }

  if (cbResult.timedOut) {
    log("WARN: Context builder timed out — proceeding without shared audit context")
  }
}
// sharedAuditContext is injected into Ash prompts during Phase 3 (Ash summoning)

Phase 0.5: Lore Layer (Risk Intelligence)

See deep-mode.md for the full Lore Layer implementation.

Skip conditions: non-git repo, --no-lore, fewer than 5 commits in lookback window (G5 guard).

Phase 1: Rune Gaze (Scope Selection)

Classify ALL project files by extension. See rune-gaze.md.

Apply --focus filter: If --focus <area> is set, only summon Ash matching that area. Apply --max-agents cap: If --max-agents N is set, limit selected Ash to N.

Large codebase warning: If total reviewable files > 150, log a coverage note.

Dry-Run Exit Point

If --dry-run flag is set, display the plan and stop. No teams, tasks, state files, or agents are created.

Delegate to Shared Orchestration

Set parameters and execute shared phases from orchestration-phases.md.

// ── Resolve session identity ──
const configDir = Bash(`cd "\${CLAUDE_CONFIG_DIR:-$HOME/.claude}" 2>/dev/null && pwd -P`).trim()
const ownerPid = Bash(`echo $PPID`).trim()

const params = {
  scope: "full",
  depth,
  teamPrefix: "rune-audit",
  outputDir: `tmp/audit/${audit_id}/`,
  stateFilePrefix: "tmp/.rune-audit",
  identifier: audit_id,
  selectedAsh,
  fileList: all_files,
  timeoutMs: 900_000,   // 15 min (audits cover more files than reviews)
  label: "Audit",
  configDir, ownerPid,
  sessionId: "${CLAUDE_SESSION_ID}" || Bash(`echo "\${RUNE_SESSION_ID:-}"`).trim(),
  maxAgents: flags['--max-agents'],
  workflow: "rune-audit",
  focusArea: flags['--focus'] || "full",
  dirScope: dir_scope,      // #20: { include: string[]|null, exclude: string[] } — resolved in Phase 0
  customPromptBlock: resolveCustomPromptBlock(flags),  // #21: from --prompt / --prompt-file (null if not set). See references/prompt-audit.md
  flags
}

// Execute Phases 1-7 from orchestration-phases.md
// Phase 1: Setup (state file, output dir)
// Phase 2: Forge Team (inscription, signals, tasks)
// Phase 3: Summon (single wave or multi-wave based on depth)
// Phase 4: Monitor (waitForCompletion with audit timeouts)
// Phase 4.5: Doubt Seer (conditional)
// Phase 5: Aggregate (Runebinder → TOME.md)
// Phase 6: Verify (Truthsight)
// Phase 7: Cleanup (shutdown, TeamDelete, state update)
//   Includes: Bash(`cd "${CWD}" && source plugins/rune/scripts/lib/workflow-lock.sh && rune_release_lock "audit"`)

Audit-Specific Post-Orchestration

After orchestration completes: (1) Truthseer Validator for high file counts (>100), (2) incremental result write-back (Phase 7.5) — gated on isIncremental && incrementalLockAcquired. Write-back parses TOME findings per file, updates state.json with per-file audit status (completed vs error with 3-strike permanent marking), recomputes coverage stats, writes session history, completes checkpoint, releases advisory lock (ownership-checked), and generates coverage report. (3) Interactive prompt for mend/review/rest.

See incremental-writeback.md for the full pseudocode.

Error Handling

Error	Recovery
Ash timeout (>5 min)	Proceed with partial results
Total timeout (>15 min)	Final sweep, collect partial results, report incomplete
Ash crash	Report gap in TOME.md
ALL Ash fail	Abort, notify user
Concurrent audit running	Warn, offer to cancel previous
File count exceeds 150	Warn about partial coverage, proceed with capped budgets
Not a git repo	Works fine — audit uses find, not git diff. Incremental degrades to mtime-based scoring.
State file corrupted	Rebuild from history/ snapshots (see incremental-state-schema.md)
State file locked (dead PID)	Detect dead PID via kill -0, remove stale lock, proceed
Concurrent incremental sessions	Second session warns, falls back to full audit
Manifest too large (>10k files)	Still functional; consider sharding for performance
Checkpoint from dead session	Clean up, start fresh batch
Disk full during state write	Pre-flight check: skip incremental if <10MB available
Error file infinite re-queue	1st error re-queue, 2nd skip-one-batch, 3rd+ mark error_permanent

Migration Guide (Concern 6)

Upgrading from non-incremental to incremental audit:

1. No migration needed — --incremental is opt-in and does not affect default behavior
2. First --incremental run creates .rune/audit-state/ and runs a fresh scan
3. All files start as never_audited and are prioritized by the scoring algorithm
4. State accumulates across sessions — coverage improves with each run
5. Use --reset to clear state and start fresh at any time

Recovery from state corruption:

1. --reset clears all state files but preserves history
2. If state.json is corrupted, it auto-rebuilds from history/ snapshots
3. If manifest.json is corrupted, next run regenerates it from the filesystem
4. Manual recovery: delete .rune/audit-state/ entirely and start fresh

References

• Phase 0 Dir Scope — Directory scope resolution (7-step validation + file scan)
• Incremental Write-Back — Post-orchestration Phase 7.5 (state update, history, checkpoint, lock release)
• Deep Mode — Lore Layer, deep pass, TOME merge
• Orchestration Phases — Shared parameterized orchestration
• Circle Registry — Ash-to-scope mapping, focus mode
• Smart Selection — File assignment, budget enforcement
• Wave Scheduling — Multi-wave deep scheduling
• Incremental Phases — Full Phase 0.0-0.4 pseudocode (extracted from SKILL.md)
• Incremental State Schema — State files, locking, atomic writes, schema migration
• Codebase Mapper — File inventory, git metadata, manifest diff
• Priority Scoring — 6-factor composite algorithm, batch selection
• Workflow Discovery — Tier 2 cross-file flow detection
• Workflow Audit — Tier 2 cross-file review protocol
• API Discovery — Tier 3 endpoint contract detection
• API Audit — Tier 3 endpoint contract review, OWASP checks
• Coverage Report — Human-readable dashboard, freshness tiers