audit

/vibeos:audit — Full Audit Cycle

Dispatch the audit agents, merge findings with consensus logic, and produce a composite report.

Communication Contract

Follow the full USER-COMMUNICATION-CONTRACT.md (docs/USER-COMMUNICATION-CONTRACT.md). Key rules:

• Lead with outcome, follow with mechanism
• Present decisions with consequences
• Introduce every concept on first use with plain English definition

Skill-specific addenda:

• Report which auditors are being dispatched
• After each auditor completes, summarize its top findings
• Explain findings in plain English first; add technical detail after that when it helps the user understand the risk
• If the user must choose how to handle findings, present options with pros, cons, and a recommendation

Prerequisites

Before starting, verify these exist:

• project-definition.json
• Source code to audit (at least one source directory with files)

If no source code exists, report "No source code to audit" and stop.

Audit Flow

Step 1: Determine Scope

If $ARGUMENTS specifies a single auditor name (security, architecture, correctness, test, evidence, product-drift, flow, invariant, dependency, delivery, red-team, contract), run only that auditor. Otherwise, run all auditors.

Read project-definition.json for:

• Source directories
• Test directories
• Stack/framework info
• Compliance targets

Step 2: Refresh Runtime Capability Matrix

Before selecting auditor dispatch mode, refresh local runtime capabilities when the detector exists:

if [ -f ".vibeos/scripts/detect-runtime-capabilities.sh" ]; then
  bash ".vibeos/scripts/detect-runtime-capabilities.sh" --project-dir "."
elif [ -f "scripts/detect-runtime-capabilities.sh" ]; then
  bash "scripts/detect-runtime-capabilities.sh" --project-dir "."
fi

Read .vibeos/runtime-capabilities.json if it exists. Use it as advisory input for runtime selection, but keep select-audit-visibility-mode.sh as the authority for same-tree versus worktree audit visibility inside VibeOS build sessions.

Step 3: Select Audit Visibility Mode

Before dispatching any auditor, choose visibility automatically:

bash scripts/select-audit-visibility-mode.sh "${ARGUMENTS:-}"

Read .vibeos/session-state.json after that command and use:

• audit_visibility_mode
• audit_dispatch_profile
• audit_snapshot_ref

Rules:

• If audit_dispatch_profile is same-tree, dispatch the *-same-tree.md auditor variants.
• If audit_dispatch_profile is worktree, dispatch the standard isolated-worktree auditors.
• If no WO or active session is in scope, default to the standard isolated-worktree auditors.
• Never stop to ask the user which mode to use during autonomous execution. The selector is the authority.

Step 4: Dispatch Audit Agents

Dispatch the selected audit agents using the chosen visibility mode. Auditors remain read-only in both modes.

Agent dispatch list:

Agent	File	Model	Purpose
Security	agents/security-auditor.md	sonnet	OWASP Top 10, secrets, injection, PII
Architecture	agents/architecture-auditor.md	sonnet	Layer violations, circular deps, boundaries
Correctness	agents/correctness-auditor.md	opus	Logic errors, missing error paths, user impact
Test Quality	agents/test-auditor.md	sonnet	Spec-first, assertion quality, mock density
Evidence	agents/evidence-auditor.md	sonnet	Documentation completeness, tracking accuracy
Product Drift	agents/product-drift-auditor.md	sonnet	Product promise drift, experience drift, stale decisions
Flow	agents/flow-auditor.md	opus	End-to-end user journey, layer handoffs, objective fidelity
System Invariants	agents/system-invariant-auditor.md	opus	State rules, ownership, idempotency, recovery, change safety
Dependency Intelligence	agents/dependency-intelligence-auditor.md	opus	Current-source dependency evidence, compatibility, lockfiles, audit output, transitive risk
Delivery Infrastructure	agents/delivery-infrastructure-auditor.md	opus	CI/CD, deployment, environment/secrets, observability, smoke checks, rollback, runbooks
Plan	agents/plan-auditor.md	opus	WO planning correctness, sequencing, canon alignment
Red Team	agents/red-team-auditor.md	opus	Adversarial corruption hunting, cheating detection
Contract	agents/contract-validator.md	sonnet	Frontend-backend contract verification (cross-boundary only)

When audit_dispatch_profile is same-tree, replace each agents/<name>.md with agents/<name>-same-tree.md.

Audit Dispatch Strategy

For codebases under 15K lines: dispatch each auditor on the full codebase (current behavior).

For codebases over 15K lines: use module-targeted dispatch:

1. Identify the top-level modules (e.g., src/gateway/, src/orchestrator/, frontend/src/)
2. Dispatch auditors per-module rather than per-audit-type
3. Each auditor gets a focused scope: "Audit security for src/platform_api/ only"
4. Aggregate findings across modules after all agents complete
5. Run cross-cutting checks (circular dependencies, contract mismatches) as a separate pass

For per-WO audits during build: only audit the files changed by this WO (incremental audit), plus their immediate dependencies. Do not audit the full codebase.

Dispatch agents that can run independently in parallel where possible using the visibility mode selected in Step 2. Pass each agent:

• The project-definition.json path
• Source directory paths
• The current WO file path (if running within a build cycle)

Step 5: Collect Findings

As each agent completes, extract its structured findings. Normalize each finding to this format:

{
  "id": "[agent]-[N]",
  "agent": "[agent name]",
  "category": "[finding category]",
  "severity": "[critical|high|medium|low|info]",
  "file": "[file path]",
  "line": "[line number or range]",
  "description": "[what was found]",
  "recommendation": "[how to fix]",
  "confidence": "[high|medium|low]"
}

If an agent fails to complete or returns unparseable output:

1. Log the failure
2. Continue with remaining agents
3. Note the missing auditor in the report

Step 6: Apply Consensus Logic

Group findings by location (file + line range overlap) and category similarity:

True Positive (high confidence): 2 or more agents flag the same location or same issue pattern.

• Merge the descriptions from all flagging agents
• Use the highest severity among them
• List all agents that flagged it

Warning (review recommended): Exactly 1 agent flags an issue.

• Keep the finding as-is
• Mark as "single-auditor finding"
• Include the agent's confidence rating

Clean: Location checked by multiple agents with no findings.

• Not reported individually
• Contributes to the overall confidence score

Step 7: Generate Composite Report

Write the report to stdout (displayed to user). Format:

## Composite Audit Report

**Date:** [today]
**Scope:** [directories audited]
**audit_visibility_mode:** [same-tree|snapshot|committed-tree|not-applicable]
**audit_snapshot_ref:** [ref|none]
**Auditors dispatched:** [list of 8 or subset]
**Auditors completed:** [count]/[dispatched]

### Executive Summary

- **True positives (2+ auditors agree):** [count]
- **Warnings (single auditor):** [count]
- **Critical findings:** [count]
- **High findings:** [count]
- **Medium findings:** [count]
- **Low/Info findings:** [count]

### Critical & High Findings (Action Required)

| # | Finding | Severity | Consensus | Agents | File | Recommendation |
|---|---|---|---|---|---|---|
| 1 | [description] | [severity] | [true_positive/warning] | [agent list] | [path:line] | [fix] |

### Medium & Low Findings (Review Recommended)

| # | Finding | Severity | Agent | File | Recommendation |
|---|---|---|---|---|---|
| 1 | [description] | [severity] | [agent] | [path:line] | [fix] |

### Auditor Summary

| Auditor | Status | Findings | Top Issue |
|---|---|---|---|
| Security | [complete/failed] | [count] | [top finding or "clean"] |
| Architecture | [complete/failed] | [count] | [top finding or "clean"] |
| Correctness | [complete/failed] | [count] | [top finding or "clean"] |
| Test Quality | [complete/failed] | [count] | [top finding or "clean"] |
| Evidence | [complete/failed] | [count] | [top finding or "clean"] |
| Product Drift | [complete/failed] | [count] | [top finding or "clean"] |
| Flow | [complete/failed] | [count] | [top finding or "clean"] |
| System Invariants | [complete/failed] | [count] | [top finding or "clean"] |
| Plan | [complete/failed] | [count] | [top finding or "clean"] |
| Red Team | [complete/failed] | [count] | [top finding or "clean"] |
| Contract | [complete/failed/skipped] | [count] | [top finding or "clean"] |

### Overall Assessment

[1-3 sentence plain English assessment of project health]

**Recommendation:** [pass/conditional pass/fail]
- pass: No critical or high findings
- conditional pass: High findings exist but are addressable
- fail: Critical findings that must be fixed before proceeding

Step 8: Save Report (if in build cycle)

If this audit was triggered from /vibeos:build, save the report to .vibeos/audit-reports/[WO-NNN]-[timestamp].md for the build log to reference.

Create the directory if it doesn't exist:

mkdir -p .vibeos/audit-reports

After saving the report, register it so session-end closure gates validate the correct report:

bash scripts/register-audit-report.sh ".vibeos/audit-reports/[WO-NNN]-[timestamp].md"

Single-Auditor Mode

When $ARGUMENTS specifies a single auditor:

• Skip consensus logic (only 1 agent)
• Use that agent's native report format
• Still save the report if in build cycle

Error Handling

• If an agent exceeds its turn limit: log timeout, continue with others
• If an agent returns no findings: record "clean" for that auditor
• If all agents fail: report the failure and suggest checking project-definition.json
• Never fabricate findings — only report what agents actually found