codex-audit

/vibeos:codex-audit — Complementary Audit Protocol

Dispatches an independent audit to Codex. Claude implements; Codex audits. All four audit types are supported. Reconciliation is mandatory — zero technical debt policy applies.

Step 1: Resolve Arguments

From $ARGUMENTS:

• plan → plan_audit
• complete or completion → completion_audit
• session → session_audit
• manual or empty → manual_audit
• --both → dual-audit mode (Claude and Codex both audit, then reconcile)
• --wo <path> → pass specified WO file to the broker
• --wait → run synchronously (foreground, wait for result)
• --background → run asynchronously (print status, exit immediately)
• --explicit → bypass significance check, run regardless of thresholds

Step 2: Gather Context

Run these in parallel before calling the broker:

# Git state
git diff --shortstat HEAD~1 HEAD 2>/dev/null || git diff --shortstat
git log --oneline -5

# Find most recent WO if none specified
ls docs/planning/ 2>/dev/null | grep -E '^WO-' | sort | tail -3

# Check for existing evidence bundles
ls docs/evidence/ 2>/dev/null | sort | tail -5

# For session audits: recent build log
tail -80 .vibeos/build-log.md 2>/dev/null || true

If no --wo was passed and you can identify the most relevant WO from context, add --wo <path>.

Step 3: Run Broker

Call the audit broker. For --both (dual-audit), auditor=both; otherwise auditor=codex (default).

bash plugins/vibeos/scripts/codex-audit-broker.sh \
  --type <audit_type> \
  --auditor <codex|both> \
  --executor claude \
  [--wo <wo_file>] \
  [--context "<brief context>"] \
  [--wait|--background] \
  [--explicit]

If broker exits with code 2 (not significant): Tell the user in one sentence that the change did not meet the significance threshold, and offer to run with --explicit to bypass it. Do not auto-run.

If broker exits with code 1 (Codex plugin not found or invocation error): Report the failure and offer the built-in VibeOS audit agents as fallback: /vibeos:audit

Step 4: Present Findings

When the broker returns output (foreground) or the result file exists (background):

1. State the verdict upfront — one line.
2. Present all findings ordered by severity: critical → high → medium → low → info.
3. For each finding: state what it is, where (file:line), and what must be done.
4. Show a pillar assessment summary table if the broker provides one.
5. If dual-audit: highlight consensus findings (both agree) vs single-auditor findings.

Do not paraphrase away severity. If Codex says blocked, say blocked.

Step 5: Reconciliation — Zero Technical Debt

This step is mandatory before any closure. Nothing is dropped.

For each finding:

critical or high

Fix before closure. No exceptions. No operator override except with explicit written justification. Do not mark the WO, plan, or session closed until fixed.

medium

Fix now if the fix is bounded and clear. If it naturally belongs in a forward WO (additive enhancement, not a defect in current work):

• Create or update that WO to include it
• Record the linkage in the audit evidence file: "Finding M-N deferred to WO-XXX"
• Must close within 1-2 work sessions — not indefinitely

low

Fix now if trivial (estimated under 30 minutes). Otherwise create a WO entry with explicit linkage to the audit evidence file.

info

Acknowledge in the evidence bundle. Fix now if trivial. WO is optional but preferred if recurring.

Rebuttal

If you disagree with a finding:

• State the rebuttal explicitly: "Finding #N: disagree — [evidence at file:line showing it is not an issue]"
• Do NOT silently ignore it
• If the evidence is ambiguous, escalate to the operator

Operator override

If the operator explicitly says "override [finding #N]" or "proceed anyway":

• Log the override in the audit evidence file: OVERRIDE: Finding #N — reason: [operator reason]
• Note which specific findings were overridden
• Proceed, but do not pretend the findings do not exist

Step 6: Record Evidence

After reconciliation, write an evidence note to the relevant evidence bundle:

mkdir -p docs/evidence/<WO_NUMBER>/

Record in docs/evidence/<WO_NUMBER>/codex-audit.md:

## Codex Complementary Audit

**Date:** [today]
**Audit type:** [type]
**Verdict:** [verdict]
**Auditors:** [codex|both]
**Result file:** .vibeos/audit/results/[filename]

### Findings Summary
| Severity | Count |
|---|---|
| Critical | N |
| High | N |
| Medium | N |
| Low | N |
| Info | N |

### Reconciliation Actions
[what was fixed, what WOs were created, any overrides logged]

Auto-Trigger Guidance

Proactively invoke this skill (without being asked) when:

1. plan_audit: You just approved or finalized a plan or WO tranche for execution AND the significance check would pass
2. completion_audit: You are about to declare a WO complete AND the significance check would pass
3. session_audit: A session closeout is about to close AND 3 or more WOs were closed this session

For auto-triggers: always ask the operator to confirm before running dual-audit (--both). Single-auditor runs can proceed without asking.

Error Handling

• Broker exit 2 (not significant): surface to user in one sentence, offer --explicit
• Broker exit 1 (invocation error): surface error, offer /vibeos:audit fallback
• Empty Codex output: report "audit incomplete", surface what was returned, do not fabricate verdict
• Codex plugin not installed: report it clearly, fall back to /vibeos:audit

Quick Reference

# Manual audit on demand (Codex audits Claude's work)
bash plugins/vibeos/scripts/codex-audit-broker.sh --type manual_audit --executor claude

# Before executing a WO tranche
bash plugins/vibeos/scripts/codex-audit-broker.sh --type plan_audit --executor claude --wo docs/planning/WO-XXX.md

# After a WO closes
bash plugins/vibeos/scripts/codex-audit-broker.sh --type completion_audit --executor claude --wo docs/planning/WO-XXX.md

# Session end
bash plugins/vibeos/scripts/codex-audit-broker.sh --type session_audit --executor claude

# Dual-audit (both models audit, then reconcile)
bash plugins/vibeos/scripts/codex-audit-broker.sh --type completion_audit --auditor both --executor claude --explicit

# Force-run even if below significance threshold
bash plugins/vibeos/scripts/codex-audit-broker.sh --type manual_audit --executor claude --explicit