---
description: |
  [TOPIC] Github Actions — audit-all is the mandatory per-package CI gate
  [DETAILS] Every scitex-* repo MUST run `scitex-dev ecosystem audit-all <pkg>` on every push and PR — the only ecosystem-wide gate that composes audit-cli / audit-mcp-tools / audit-skills / audit-python-apis / audit-project. Covers the wiring (a normal `tests/develop/test_audit.py`, not a separate workflow), the required pinned `scitex-dev[cli-audit]` dep in `[dev]`, the exit-code failure policy, per-package adoption via `write-audit-test`, the `SCITEX_DEV_SKIP_AUDIT` bypass (never on main/develop), and why the cross-package §5b passthrough check makes it mandatory not optional. Companion to [07_github-actions.md](07_github-actions.md).
tags: [scitex-general-package-github-actions]
---

# audit-all — the mandatory per-package CI gate

> Parent leaf: [`07_github-actions.md`](07_github-actions.md).

## Per-package audit: `scitex-dev ecosystem audit-all <pkg>` is mandatory

Every `scitex-*` repo MUST run `scitex-dev ecosystem audit-all <pkg>` on every push and PR. This is the only ecosystem-wide gate that composes:

- `audit-cli` (§1–§11 click compliance)
- `audit-mcp-tools` (§1–§6 MCP compliance, including the §3 four-subcommand check)
- `audit-skills` (skill leaf shape, frontmatter, line budgets)
- `audit-python-apis` (Python API parity with CLI/MCP surfaces)
- `audit-project` (PS-101–PS-134 project-structure rules — readme, sphinx, version pins, CHANGELOG, license, etc.)

Without this gate, drift accumulates silently — packages can ship help text that contradicts the click tree, MCP tools that don't trace back to a Python API, missing CHANGELOG entries, or stale skill leaves. The §5b umbrella-passthrough rule is enforceable only when both the umbrella and the standalone run audit-all on the same commit.

### Wiring: a normal test, not a separate workflow

Audit-all rides on the package's existing test infrastructure — no
dedicated `.github/workflows/audit.yml`. The package's test workflow
imports the shared helper from scitex-dev and asserts a clean run:

```python
# tests/develop/test_audit.py — generated by `write-audit-test`
import shutil
import pytest


def test_audit_all_clean():
    if shutil.which("scitex-dev") is None:
        pytest.skip(
            "scitex-dev not installed — add `scitex-dev[cli-audit]` "
            "to [project.optional-dependencies.dev]"
        )
    from scitex_dev.testing import audit_all_for_package

    audit_all_for_package("<pkg-short-name>")
```

Where `<pkg-short-name>` matches the entry in `scitex_dev._ecosystem._core.ECOSYSTEM` (e.g. `scitex-io`, `scitex-cloud`, `scitex-hpc`, plus branded packages like `socialia` and `figrecipe`).

The helper runs `scitex-dev ecosystem audit-all <pkg>` as a
subprocess and raises `AssertionError` on nonzero exit. The full
stdout+stderr are captured into the test report so the failing rule,
its skill-tree pointer, and the escalation path are all visible
without re-running the audit by hand. Local `python -m pytest .`
gives the developer the same signal CI does.

### Required dependency: pin scitex-dev in `[dev]`

Every PyPI release of `scitex-dev` may add new audit rules; an
unpinned install makes a previously-green test go red overnight
without any change to the package being audited. Each package's
`pyproject.toml [project.optional-dependencies.dev]` MUST include:

```toml
[project.optional-dependencies]
dev = [
    "pytest>=7.0",
    "scitex-dev[cli-audit]==<X.Y.Z>",   # pin the version that's currently green
    # ...
]
```

To upgrade: `pip install -U scitex-dev`, then re-run
`scitex-dev ecosystem write-audit-test <pkg> --force` (the test stub
itself doesn't change, but you'll bump the pin in `pyproject.toml`
manually as part of the same change).

### Failure policy

The exit code is the single source of truth:

| Sub-auditor exit | Severity present                  | audit-all exit |
|------------------|-----------------------------------|----------------|
| 0                | none, or warn-only                | 0 (green)      |
| 1                | at least one error-severity rule  | 1 (red)        |
| 2                | not-auditable / install error     | 1 (red)        |

The test fails on any nonzero exit. As of 2026-05-06 every actionable
audit rule is `error` severity, so a violation = failed test = red CI.
Use the existing test workflow's branch-protection settings to gate
merges; no `continue-on-error` is involved.

### Per-package adoption

Use the helper to materialise the canonical test stub:

```bash
scitex-dev ecosystem write-audit-test <pkg-short-name>
```

Writes `tests/develop/test_audit.py` (force-required to overwrite),
plus `tests/develop/__init__.py` and an empty `tests/conftest.py`
when missing.

### Bypass — exceptions and temporal remedy

The audit gate is mandatory in steady state, but two situations
legitimately call for a temporary skip:

1. **Remediation in flight.** A package is mid-cleanup of pre-existing
   violations and the noise is blocking unrelated test runs.
2. **Local dev without the audit corpus.** A developer working on a
   feature on a machine where `scitex-dev[cli-audit]` isn't installed.

Both bypass via the environment variable:

```bash
SCITEX_DEV_SKIP_AUDIT=1 python -m pytest .
```

When set, `audit_all_for_package` calls `pytest.skip()` instead of
running the audit subprocess. The skip line shows up clearly in the
report so it's never silent.

**Hard rule.** CI for `main`/`develop` MUST NOT set
`SCITEX_DEV_SKIP_AUDIT`. The variable is for ephemeral local sessions
and short-lived cleanup branches only — every push to a release-track
branch must run the audit. If a package needs a sustained exemption
from a specific rule, demote that rule to `warn` in scitex-dev (with a
documented false-positive history) instead of muting the whole gate.

### Why this is mandatory, not optional

`scitex-dev ecosystem audit-all` is the *only* place where umbrella-side rules (§5b passthrough) and standalone-side rules (§3 mcp subcommands, §1a tab completion, §10 positional ordering) are checked together. Running individual `audit-cli` or `audit-mcp-tools` invocations from local shells doesn't catch the cross-package drift that's already cost the ecosystem ~16 packages × multiple commits to clean up (the 2026-05-06 sweeps).
