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.

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

1. Collect inventory.

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

1. Run shared quality gates.

   .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.

   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).

   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.

   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.

   .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": []
}