---
name: openspec-audit
description: Orchestrates a full compliance audit at one of five depths (quick, standard, strict, release, forensic) by composing openspec-verify, openspec-drift, and openspec-traceability. Use before /gsd-ship, or any time a broader confidence check is wanted than the per-phase verify:post step alone gives.
allowed-tools: Read, Bash
license: MIT
metadata:
  author: openspec-gsd-integration
  version: "0.1.0"
---

## Purpose

A single entry point for "how sure are we, really" at whatever depth the moment calls for — from a fast sanity check to a full forensic reconstruction of an existing, un-audited codebase. Composes the other skills; implements no verification logic of its own.

## Invocation conditions

- Directly, any time: `/openspec-audit [quick|standard|strict|release|forensic]` (defaults to `workflow.openspec_audit_mode`, `standard`).
- Recommended immediately before `/gsd-ship` on anything beyond a trivial phase, even though `ship:pre`'s gate only technically requires `openspec-verify`'s `status: passed`.

## Required inputs

- Mode (one of the five below; defaults per config).
- Scope: a single change-id, or "everything currently unshipped" (default).

## Files read

Depends on mode — see table. Never writes to `openspec/` in any mode.

## Files this skill may write

- `.planning/openspec/AUDIT-SUMMARY.md` (overwritten each run — it is a snapshot, not a log; `EVIDENCE.json` is the append-only log, written by `openspec-verify`/`openspec-traceability`)

## The five modes

| Mode | Composes | Checks |
|---|---|---|
| **quick** | `openspec-verify` (cached, no re-run if fresh) | Task completion + targeted scenario tests only. Seconds, not minutes. |
| **standard** | `openspec-verify` (fresh run) + `openspec-traceability` | Full requirement/scenario coverage + regression cross-reference (Levels 1-5 above). This is the default and what `ship:pre` effectively expects to have run recently. |
| **strict** | standard + `openspec-drift` (Level 6) | Adds design compliance, non-functional requirements (perf/security if the project's OpenSpec specs declare any), undocumented-behavior scan. |
| **release** | strict + release-readiness checks | Adds: migrations present and reversible, rollback plan documented in `design.md` or `proposal.md`, observability (logging/metrics mentioned for the new behavior), docs updated, backward compatibility of any changed API contract. |
| **forensic** | independent reconstruction, ignores prior `EVIDENCE.json` | For a codebase with existing, unaudited implementation: reconstructs actual behavior from code+tests, diffs it against `openspec/specs/` history (via `openspec` archive dates / git blame), and reports likely undocumented drift causes — this is the mode `openspec-bootstrap`'s brownfield note points to. |

## Algorithm

1. Resolve mode (arg > `workflow.openspec_audit_mode` config > `standard`).
2. Resolve scope (explicit change-id, or every change with a phase not yet shipped per `.planning/STATE.md`).
3. Run the composed skills for that mode, in the order in the table (never re-implementing their checks here).
4. Aggregate into `.planning/openspec/AUDIT-SUMMARY.md`: one row per requirement across the scope, the mode used, and a top-line verdict.
5. If any composed skill reports a finding requiring a fix, hand each one to `openspec-repair` — this skill classifies nothing itself; classification is `openspec-execute`'s and `openspec-repair`'s job.

## Outputs

`.planning/openspec/AUDIT-SUMMARY.md` — human-readable, one audit run's full picture; safe to regenerate before every Ship.

## Failure states

- Requested `release` or `strict` mode but a composed check (e.g. `openspec-drift`) cannot resolve cleanly → the whole audit reports `human_needed`, same discipline as `openspec-verify` — never silently downgrades to a lower mode's verdict.

## Guardrails

- Never invents a passing verdict for a mode's checks it didn't actually run (e.g. `release` mode always runs the full `strict` chain first — it cannot skip straight to release-only checks).
- `forensic` mode never overwrites prior evidence — it is explicitly a *separate*, comparison-oriented report.

## Idempotency

`quick`/`standard`/`strict`/`release` are safe to re-run; each overwrites `AUDIT-SUMMARY.md` with a fresh snapshot. `forensic` mode's report is timestamped and additive (multiple forensic runs over time are meant to be compared, not deduplicated).

## Example

```
$ /openspec-audit release
[openspec-audit] mode=release, scope=add-health-check-endpoint
  strict checks: PASS (2/2 requirements, 0 drift findings)
  release checks: rollback plan ✓ (design.md §Rollback) · observability ✓ (structured log line added) · docs: MISSING
  → status: gaps_found (docs) — routed to openspec-repair
```