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 ] [--max-agents ] [--dry-run] [--no-lore] [--deep-lore] [--standard] [--incremental] [--resume] [--status] [--reset] [--tier <file|workflow|api|all>] [--force-files ] [--dirs <path,...>] [--exclude-dirs <path,...>] [--prompt ] [--prompt-file ]" 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

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

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