audit

Audit

Run a linear configuration and workflow audit loop.

Input Schema

{
  "scope": "config|skills|agents|all",
  "target": "optional path",
  "mode": "upgrade|adversarial",
  "skip_gate": false,
  "done_when": "drift and broken references are ranked with gate result; fix level chosen interactively unless skip_gate=true"
}

Workflow (Exact Commands)

1. Create run directory.

``bash TS=$(date -u +%Y-%m-%dT%H-%M-%SZ) OUT_DIR=".reports/codex/audit/$TS" mkdir -p "$OUT_DIR" ``

1. Collect inventory.

``bash find .codex -maxdepth 4 -type f | sort >"$OUT_DIR/inventory.txt" ``

1. Run shared quality gates.

``bash .codex/skills/_shared/run-gates.sh \ --out "$OUT_DIR" \ --lint "${LINT_CMD:-bash -lc 'if command -v ruff >/dev/null 2>&1; then ruff check .codex; else UV_CACHE_DIR=${UV_CACHE_DIR:-/tmp/codex-uv-cache} uv run --no-sync ruff check .codex; fi'}" \ --format "${FORMAT_CMD:-bash -lc 'if command -v ruff >/dev/null 2>&1; then ruff format --check .codex; else UV_CACHE_DIR=${UV_CACHE_DIR:-/tmp/codex-uv-cache} uv run --no-sync ruff format --check .codex; fi'}" \ --types "${TYPES_CMD:-true}" \ --tests "${TESTS_CMD:-true}" \ --review "${REVIEW_CMD:-git diff --check}" ``

1. Detect drift and broken references.

``bash rg -n "config_file|skills/|quality-gates|run-gates.sh|write-result.sh" .codex >"$OUT_DIR/reference-scan.txt" ``

1. Audit spawn-pattern coverage and overlap in AGENTS.md (instruction-level check).

``bash rg -n "^### Spawn $(.+) when:" .codex/AGENTS.md >"$OUT_DIR/spawn-sections.txt" rg -n "Automatic spawn patterns \\(all agents\\)|Collaboration team patterns" .codex/AGENTS.md >"$OUT_DIR/spawn-policy-sections.txt" ``

1. Review agent-roster consistency.

``bash rg -n "^(name|description|developer_instructions)" .codex/agents >"$OUT_DIR/agent-roster-scan.txt" ``

Classify overlap findings explicitly as keep, sharpen, or merge-prune:

• keep: distinct decision surface remains
• sharpen: role stays, but boundary text should tighten
• merge-prune: role no longer owns a distinct acceptance criterion

1. Classify findings using ../_shared/severity-map.md.

1. Write mandatory result artifact.

``bash .codex/skills/_shared/write-result.sh \ --out "$OUT_DIR/result.json" \ --status "$STATUS" \ --checks-run "lint,format,types,tests,review" \ --checks-failed "$CHECKS_FAILED" \ --critical "$CRITICAL" \ --high "$HIGH" \ --medium "$MEDIUM" \ --low "$LOW" \ --confidence "$CONFIDENCE" \ --artifact-path "$OUT_DIR/result.json" ``

Fail-fast Rules

1. Missing .codex inventory => fail.
2. Shared gate script missing => fail.
3. Broken config/skill references in critical paths => fail.
4. Missing spawn coverage for any configured agent => fail.
5. Unclear or overlapping spawn intent without explicit collaboration-team guidance => fail.
6. Agent overlap left without a keep/sharpen/merge-prune decision => fail.
7. Result artifact missing => fail.

Output Contract

Use shared gate schema from ../_shared/quality-gates.md.

Minimum artifact payload:

{
  "status": "pass|fail|timeout",
  "checks_run": [
    "lint",
    "format",
    "types",
    "tests",
    "review"
  ],
  "checks_failed": [],
  "findings": {
    "critical": 0,
    "high": 0,
    "medium": 0,
    "low": 0
  },
  "confidence": 0.0,
  "artifact_path": ".reports/codex/audit/<timestamp>/result.json",
  "recommendations": [],
  "follow_up": []
}