# Harness audit checks reference

URL: https://developertoolkit.ai/en/reference/harness-audit-checks/
Description: Catalogue of the six Software Factory stations, deterministic repo checks, and level caps evaluated locally by @wondelai/harness-audit.

`@wondelai/harness-audit` evaluates a repository deterministically across six weighted Software Factory stations—Intent, Harness, Loop, Graph, Verification, and Release—and maps the resulting evidence onto Dan Shapiro's Autonomy Ladder (Level 0–5). Every check runs locally with zero network uploads and links directly to its corresponding pattern in this canon.

Developers, tech leads, and CTOs use this reference to inspect why a repository received a specific score or Autonomy Level cap, which concrete artifacts unblock the next rung, and how to turn audit checks into continuous CI guardrails. For step-by-step usage, optional interviews, and remediation prompts, see the [harness audit guide](/en/workflows/harness/harness-audit-guide/).

## Station 1 — Intent

Evaluates whether the repository provides every coding agent concise, non-duplicated context and specification discipline before code edits begin.

| Check area | What passes | Guide |
| --- | --- | --- |
| Root instruction file | `AGENTS.md` (or tool equivalent) exists with real repo boundaries and verification commands | [AGENTS.md and concise context](/en/workflows/context/agents-md-context/) |
| Single source of truth | `CLAUDE.md` delegates via `@AGENTS.md` rather than duplicating policy text | [Shared team rules](/en/teams/adopt/team-collaboration/) |
| Instruction budget | Root brief stays compact (≤ 150 lines) without generic filler or copied boilerplate | [Pruning context files](/en/workflows/context/pruning-context-files/) |
| Scoped rules & skills | Path-scoped rules (`.claude/rules/`, `.cursor/rules/*.mdc`) and reusable `SKILL.md` skills | [Agent skills](/en/ecosystem/skills/) |
| Specification artifacts | PR/issue templates or spec and plan structure capturing acceptance criteria before coding | [Spec-driven development](/en/workflows/plan/spec-driven-development/) |

## Station 2 — Harness

Evaluates whether permissions, lifecycle hooks, MCP integrations, and secret boundaries are enforced mechanically by the environment rather than by prompt politeness.

| Check area | What passes | Guide |
| --- | --- | --- |
| Permissions & sandbox | Explicit allow/deny or sandbox/approval posture (flags retired policies such as Codex `untrusted`) | [Permissions and sandboxing](/en/workflows/harness/permissions-and-sandboxing/) |
| Lifecycle hooks | Deterministic `PreToolUse`, `PostToolUse`, or `Stop` hooks with loop protection (`stop_hook_active`) | [Agent hooks](/en/workflows/harness/agent-hooks/) |
| MCP hygiene | Zero archived or hallucinated packages, deprecated `/sse` endpoints, or plaintext Bearer tokens | [Model Context Protocol](/en/ecosystem/mcp/) |
| Secret protection | `.env` / `.dev.vars` gitignored, `.env.example` committed, zero leaked credentials in config | [Agent identity and secrets](/en/org/agent-identity-and-secrets/) |

## Station 3 — Loop

Evaluates whether an agent can verify its own edits fast and reproducibly through one deterministic command.

| Check area | What passes | Guide |
| --- | --- | --- |
| Single-command verify | Unified `check` / `verify` / `test` + `lint` + `typecheck` command executable locally and in CI | [Making a codebase agent-ready](/en/workflows/harness/agent-ready-codebase/) |
| Strict static types | Strict TypeScript or equivalent static type checking enabled across source paths | [Code quality and verification](/en/workflows/test/) |
| Fast linter & formatter | Deterministic formatter and linter configured with non-interactive CI check mode | [The feedback loop](/en/method/lifecycle/test/) |
| Reproducibility | Committed lockfile and pinned runtime version matching CI | [Agent-ready codebase](/en/workflows/harness/agent-ready-codebase/) |

## Station 4 — Graph

Evaluates whether concurrent agents can execute parallel tasks without colliding on branches, ports, databases, or working state.

| Check area | What passes | Guide |
| --- | --- | --- |
| Worktree isolation | Worktree workflow script or `.worktreeinclude` setup isolating checkouts per task | [Git worktrees](/en/workflows/harness/git-worktrees/) |
| Ephemeral ports & state | Per-worktree local ports and isolated local database/cache state | [Ephemeral environments](/en/workflows/harness/ephemeral-environments/) |
| Subagents & workflows | Scoped read-only or worktree-isolated subagent definitions (`.claude/agents/`, Codex `[agents]`) | [Orchestration patterns](/en/workflows/automate/orchestration-patterns/) |

## Station 5 — Verification

Evaluates whether automated oracles are strong enough to justify reviewing evidence instead of every generated line.

| Check area | What passes | Guide |
| --- | --- | --- |
| Unit & E2E suites | Substantive unit and end-to-end tests covering behavioral contracts | [Oracle strength](/en/workflows/test/oracle-strength/) |
| Oracle protection | `CODEOWNERS` or CI rules guarding test suites, gates, and workflows against silent weakening | [Protecting the oracle](/en/workflows/test/protect-the-oracle/) |
| Test quality scan | Low `.skip`/`.only` counts, zero tautological assertions, minimal lint or type suppressions | [Slop detection](/en/workflows/test/slop-detection/) |
| Automated PR review | Configured Bugbot (`.cursor/BUGBOT.md`), Claude/Codex review, or automated PR review gates | [Reviewing agent PRs](/en/workflows/ship/agent-pr-review/) |
| Fitness functions | Automated architectural layering, bundle, dependency, or security checks | [Architecture fitness functions](/en/workflows/test/fitness-functions/) |

## Station 6 — Release

Evaluates whether merged agent work reaches production safely with auditable evidence and rollback readiness.

| Check area | What passes | Guide |
| --- | --- | --- |
| CI pull-request gates | Required automated lint, typecheck, and test workflows running on every PR | [Deploy and production gates](/en/method/lifecycle/deploy/) |
| Evidence PR template | PR checklist capturing executed checks, risk class, sensitive paths, and rollback notes | [The evidence bundle](/en/workflows/ship/evidence-bundle/) |
| Dependency & observability | Automated dependency verification plus error tracking and structured production telemetry | [Keeping an agent codebase healthy](/en/workflows/operate/codebase-health/) |

## How station scores and hard level caps prevent inflated ratings

Weighted points summarize breadth, while hard level caps enforce architectural prerequisites. A repository with a tidy `AGENTS.md` and rich skills still caps at Level 2 when it lacks deterministic test suites and required CI checks:

| Autonomy Level | Prerequisite station evidence |
| --- | --- |
| **Level 1–2** | Root instruction file plus reproducible build and test commands |
| **Level 3** | Single-source instructions, fast local verification loop, explicit permission posture, and CI PR gates |
| **Level 4** | Strong Verification station (real tests, oracle protection, automated PR review) plus Graph isolation |
| **Level 5** | Complete six-station coverage including evidence bundles, fitness functions, and release observability |

## How to verify your repository and enforce a CI bar

Run the scanner locally to inspect every failing check, and wire CI mode into pull requests so harness health ratchets upward over time:

```bash
npx @wondelai/harness-audit
npx @wondelai/harness-audit --ci --min-score 65
```

Pass `--deep` when you want qualitative inspection of instruction signal-to-noise and test oracle strength using your local `claude` or `codex` CLI; zero code leaves your machine during the default deterministic scan. For tool-specific configuration schemas flagged by any check, consult the official docs for [Claude Code](https://code.claude.com/docs), [OpenAI Codex](https://developers.openai.com/codex), [Cursor](https://cursor.com/docs), [Agent Skills](https://agentskills.io), and [MCP](https://modelcontextprotocol.io).

**Interactive walkthrough**

Explore all six stations and copy ready-to-run commands at [`/en/harness-audit/`](/en/harness-audit/).

## When audit checks flag false positives or stubborn caps

- **A monorepo scores lower than individual packages.** Running the scanner at a wrapper root that lacks top-level scripts misses package-level test suites. Recovery: run the audit against each active service root or expose unified root verification scripts that fan out cleanly.
- **Retired policy keys fail Station 2 even though local runs appear to work.** Legacy config such as Codex `approval_policy = "untrusted"` or deprecated `.cursorrules` files breaks silently or fails on upgraded runners. Recovery: migrate to active `sandbox_mode` + `approval_policy` (`on-request`, `never`, `granular`) or `.cursor/rules/*.mdc` per official docs.
- **High test counts still trigger Station 5 warnings.** Suites padded with tautological assertions, `.skip` markers, or broad type suppressions pass line counts without proving behavior. Recovery: audit failing assertions with [oracle strength](/en/workflows/test/oracle-strength/) and lock test paths in `CODEOWNERS`.
- **Checks pass on one laptop but fail in CI.** User-scoped settings (`~/.claude/`, `~/.codex/`) never travel to CI runners or cloud VMs. Recovery: commit shared permissions, hooks, rules, and `.mcp.json` into the repository.

## Next steps from the check catalogue

- [Harness audit guide](/en/workflows/harness/harness-audit-guide/) — Run the CLI, use the 7-question interview, and generate tailored remediation prompts.
- [One map: levels and stages](/en/ladder/one-map/) — See how the six stations align with Dan Shapiro's Autonomy Ladder.
- [Harness audit interactive page](/en/harness-audit/) — Run npx @wondelai/harness-audit and preview station scoring.
- [Repo Diagnostic & Team Working Day](/en/services/) — Fixed-scope audit and hands-on remediation across multi-repo engineering teams.
