# `docs/audits/`

This directory holds dated audit + release-readiness artifacts that
accumulate over time. Anything generated by a session-bound audit pass
(closure replay, open-issue probe, regression-lock inventory, release
readiness, doc audit) lives here.

## Convention

- **Filename shape**: `<kind>-<scope>-<YYYY-MM-DD>.md` for dated audits,
  `<kind>-<scope>-<version>.md` for release-bound artifacts.
  Lowercase + hyphenated. Examples:
  - `closure-replay-2026-05-17.md`
  - `open-issues-probe-2026-05-17.md`
  - `stage-d-regression-locks-2026-05-17.md`
  - `release-readiness-v1.2.0.md`
- **NOT at repo root.** Pre-#733 the first batch of audits landed at the
  repo root (`ISSUE-AUDIT-*.md`, `DOC-AUDIT-*.md`, `RELEASE-READINESS-*.md`).
  Those got moved here in PR for #733 and renamed lowercase-hyphen for
  consistency. Future audits go here directly.
- **Not auto-pruned.** These docs are session-history artifacts — they
  describe what was true on a specific date, not the current state.
  Older audits stay around as a paper trail; the most recent one is the
  authoritative current snapshot.

## Reading order (chronological newest-first)

| File | Kind | Notes |
|---|---|---|
| `closure-replay-2026-05-17.md` | Stage A of the ironclad sweep | re-verifies all session-recent closures |
| `open-issues-probe-2026-05-17.md` | Stage C of the ironclad sweep | code-state probe of every open issue |
| `stage-d-regression-locks-2026-05-17.md` | Stage D of the ironclad sweep | regression-lock inventory + new CI guards |
| `issue-audit-2026-05-17.md` | First-pass issue audit | superseded by closure-replay |
| `doc-audit-2026-05-17.md` | Documentation audit | 7 staleness items addressed in PR #727 |
| `release-readiness-v1.2.0.md` | Release-readiness snapshot | user-gated items the v1.2.0 ceremony needs |

## Methodology

[`methodology.md`](methodology.md) collects the conventions the audit
passes surfaced — PR-body test-count discipline, source-comment
promises, audit-doc location, and the 5 patterns Stage A protects
against. Update it when a new lesson lands.

## Relation to the `cupertino` audit methodology

Each Stage of the ironclad-sweep methodology produces one doc here:

- **Stage A** — closure replay (re-verify recent closures against acceptance)
- **Stage B** — older-closures sample (deferred, currently not run)
- **Stage C** — open-issue currency probe
- **Stage D** — regression locks (test/lint/CI guards per confirmed closure)
- **Stage E** — process changes (closure protocol template) — deferred

The methodology itself is described in `closure-replay-2026-05-17.md`'s
`## Method` section. Future audit passes should follow the same shape.

## Adding a new audit

1. Pick the canonical filename per the convention above.
2. Drop the markdown in this directory (NOT at repo root).
3. Cross-link from CHANGELOG if the audit produced shipped changes, or
   from the PR body that the audit triggered.
4. Don't backfill old audits into the new naming — leave the historical
   paper trail in place.
