PureXML/docs/rules-swift-audit.md

# rules-swift Audit

Date: 2026-06-30

This audit checks PureXML against the Swift rule set at
<https://codeberg.org/Mihaela/rules-swift>. It separates mechanical proof from
architecture findings. Fill every row before claiming conformance. A row left at
`Gap` or `Partial` keeps `scripts/check-rules-swift.sh` red, which is the
intended behavior until the repo actually conforms.

## Current Verdict

| Area | Status | Evidence |
|---|---|---|
| Codified mechanical rules | Pass | `scripts/check-rules-swift.sh` wires leak, corpus-coverage, namespacing, validation-coverage, target pairing, and anti-pattern greps |
| Local mechanical gates | Pass | `scripts/check-local-gate.sh` runs the rules gate, style gate, build, and tests |
| Hook installation | Pass | `.githooks/commit-msg` and `.githooks/pre-commit` present; `scripts/install-hooks.sh` verifies rejection |
| Formatting and linting | Pass | `.swiftformat` and `.swiftlint.yml` committed; SwiftFormat runs before SwiftLint |
| Tests | Pass | `Tests/` and `PublicAPITests/` carry the parser, emitter, schema, and conformance suites |
| Validation coverage gate | Pass | `scripts/check-validation-coverage.sh` over `docs/validation-coverage-registry.txt` |
| Public CI backstop | Pass | `.github/workflows/rules-swift.yml` plus existing style and per-OS build workflows |
| Pre-UI layer | Not applicable | Headless library; no UI target |
| DocC documentation | Gap | DocC coverage not yet audited against `documentation.md` |
| Multi-renderer UI proof | Not applicable | No UI or renderer layer in this package |

## Public Corpus Coverage

Rules corpus last read: 2026-06-30 (pinned snapshot `97dc70f`).

Rules corpus file count: 88.

Rules corpus refreshed to rules-swift v2.14.0 (e624c8c) on 2026-11-02. New since v1.1.2: 21 rule files, listed in the tables below as NOT yet audited against this repository (a refresh of the pinned copy, not a conformance claim). The acceptance commands of both rules were run on `Sources` (372 Swift files searched) on 2026-11-02 and printed nothing. The rules' app-level tests (every pose, the fold on the simulator, the pane UI test) belong to an app and are not run and not claimed here. Changed since v1.1.2: `.github/pull_request_template.md`, `CHANGELOG.md`, `README.md`, `code-style.md`, `concurrency.md`, `core/README.md`, `core/brainstorming.md`, `core/file-naming.md`, `core/folder-grouping.md`, `core/writing-plans.md`, `cross-platform.md`, `dependency-injection.md`, `documentation.md`, `exp/README.md`, `exp/app-target.md`, `exp/build-performance.md`, `exp/common-mistakes.md`, `exp/critical-rules.md`, `exp/dependency-management.md`, `exp/implementation-patterns.md`, `exp/migration.md`, `exp/package-swift.md`, `exp/testing.md`, `exp/verification.md`, `exp/when-to-create.md`, `framework-policy.md`, `linux-server.md`, `namespacing.md`, `package-architecture.md`, `package-import-contract.md`, `package-structure.md`, `parsing-rules.md`, `scripts/check-namespacing.sh`, `scripts/leak-gate.sh`, `shared-protocols.md`, `testing.md`, `ui/appkit-views.md`, `ui/components.md`, `ui/flowspec.md`, `ui/pom.md`, `ui/swiftui-views.md`, `ui/uikit-views.md`, `ui/view-models.md` (see the canon's CHANGELOG); none adds or alters an acceptance command this repository runs. The files new since the last full read are listed and not yet audited against this repository.

<!--
  Every Markdown or shell file in the pinned rules-swift corpus MUST appear as a
  backticked path in the table below. scripts/check-rules-corpus-coverage.sh
  fails if any corpus file is missing here, and re-derives the count above, so
  no public rule source can be silently omitted or changed without updating this
  audit. If the corpus changes, update the count and the rows together.
-->

The local gate verifies that every Markdown or shell file in the public
`rules-swift` checkout selected by `RULES_SWIFT_DIR` is named in this section and
that the pinned snapshot digest matches `docs/rules-swift-corpus.sha256`. That
does not mean every rule is fully satisfied; it means no public rule source can
be silently omitted.

| Public rule source | Coverage |
|---|---|
| `.github/pull_request_template.md` | Vendored, pinned |
| `business-rules-and-constraints.md` | Vendored, pinned |
| `CHANGELOG.md` | Vendored, pinned |
| `code-style.md` | Vendored, pinned |
| `concurrency.md` | Vendored, pinned |
| `CONTRIBUTING.md` | Vendored, pinned |
| `CONVENTIONS.md` | Vendored, pinned |
| `core/brainstorming.md` | Vendored, pinned |
| `core/commits.md` | Vendored, pinned |
| `core/file-naming.md` | Vendored, pinned |
| `core/first-principles-analysis.md` | Vendored, pinned |
| `core/folder-grouping.md` | Vendored, pinned |
| `core/git-discipline.md` | Vendored, pinned |
| `core/no-shortcuts-first-principles.md` | Vendored, pinned |
| `core/oracle-first.md` | Vendored, pinned |
| `core/proof-discipline.md` | Vendored, pinned |
| `core/README.md` | Vendored, pinned |
| `core/round-trip-transformation.md` | Vendored, pinned |
| `core/rules.md` | Vendored, pinned |
| `core/self-improve.md` | Vendored, pinned |
| `core/systematic-debugging.md` | Vendored, pinned |
| `core/testing-discipline.md` | Vendored, pinned |
| `core/verification.md` | Vendored, pinned |
| `core/writing-plans.md` | Vendored, pinned |
| `cross-platform.md` | Vendored, pinned |
| `dependency-injection.md` | Vendored, pinned |
| `documentation-search.md` | Vendored, pinned |
| `documentation.md` | Vendored, pinned |
| `domain-first.md` | Vendored, pinned |
| `exp/app-target.md` | Vendored, pinned |
| `exp/build-performance.md` | Vendored, pinned |
| `exp/common-mistakes.md` | Vendored, pinned |
| `exp/critical-rules.md` | Vendored, pinned |
| `exp/dependency-management.md` | Vendored, pinned |
| `exp/implementation-patterns.md` | Vendored, pinned |
| `exp/migration.md` | Vendored, pinned |
| `exp/package-swift.md` | Vendored, pinned |
| `exp/README.md` | Vendored, pinned |
| `exp/testing.md` | Vendored, pinned |
| `exp/verification.md` | Vendored, pinned |
| `exp/when-to-create.md` | Vendored, pinned |
| `formatting-and-linting.md` | Vendored, pinned |
| `framework-policy.md` | Vendored, pinned |
| `linux-server.md` | Vendored, pinned |
| `namespacing.md` | Vendored, pinned |
| `openapi-generated.md` | Vendored, pinned |
| `package-architecture.md` | Vendored, pinned |
| `package-import-contract.md` | Vendored, pinned |
| `package-structure.md` | Vendored, pinned |
| `parsing-rules.md` | Vendored, pinned |
| `README.md` | Vendored, pinned |
| `scripts/check-namespacing.sh` | Vendored, pinned |
| `scripts/leak-gate.sh` | Vendored, pinned |
| `shared-protocols.md` | Vendored, pinned |
| `testing.md` | Vendored, pinned |
| `ui/appkit-views.md` | Vendored, pinned |
| `ui/colors.md` | Vendored, pinned |
| `ui/components.md` | Vendored, pinned |
| `ui/flowspec.md` | Vendored, pinned |
| `ui/fonts.md` | Vendored, pinned |
| `ui/native-per-platform.md` | Vendored, pinned |
| `ui/pom.md` | Vendored, pinned |
| `ui/pre-ui-layer.md` | Vendored, pinned |
| `ui/swiftui-views.md` | Vendored, pinned |
| `ui/three-renderers.md` | Vendored, pinned |
| `ui/uikit-views.md` | Vendored, pinned |
| `ui/view-models.md` | Vendored, pinned |
| `validation-rules.md` | Vendored, pinned |
| `accessibility.md` | Listed (new since v1.1.2; NOT yet audited against this repository) |
| `app-intents.md` | Listed (new since v1.1.2; NOT yet audited against this repository) |
| `app-logging.md` | Listed (new since v1.1.2; NOT yet audited against this repository) |
| `conventions.md` | Listed (new since v1.1.2; NOT yet audited against this repository) |
| `crash-and-state-reporting.md` | Listed (new since v1.1.2; NOT yet audited against this repository) |
| `help.md` | Listed (new since v1.1.2; NOT yet audited against this repository) |
| `iphone-duo.md` | Listed (acceptance commands run on Sources, all empty; app-level tests not run, no app here) |
| `scripts/check-changelog-touched.sh` | Tracked; canon self-audit tooling, not applicable to this consumer repo. |
| `scripts/check-core-sync.sh` | Tracked; canon self-audit tooling, not applicable to this consumer repo. |
| `scripts/check-file-names.sh` | Tracked; canon self-audit tooling, not applicable to this consumer repo. |
| `scripts/check-issue-body-staleness.sh` | Tracked; canon self-audit tooling, not applicable to this consumer repo. |
| `scripts/check-links.sh` | Tracked; canon self-audit tooling, not applicable to this consumer repo. |
| `scripts/check-repo.sh` | Tracked; canon self-audit tooling, not applicable to this consumer repo. |
| `scripts/check-rule-structure.sh` | Tracked; canon self-audit tooling, not applicable to this consumer repo. |
| `scripts/check-version-bumped.sh` | Tracked; canon self-audit tooling, not applicable to this consumer repo. |
| `scripts/sync-priority-label.sh` | Tracked; canon self-audit tooling, not applicable to this consumer repo. |
| `scripts/sync-rules.sh` | Tracked; canon self-audit tooling, not applicable to this consumer repo. |
| `scripts/test-gates.sh` | Tracked; canon self-audit tooling, not applicable to this consumer repo. |
| `ui/appuikit.md` | Listed (new since v1.1.2; NOT yet audited against this repository) |
| `ui/pane-layout.md` | Listed (acceptance commands run on Sources, all empty; app-level tests not run, no app here) |
| `versioning.md` | Listed (new since v1.1.2; NOT yet audited against this repository) |

## Rule Matrix

<!--
  One row per rule file that applies to this repo. Status is one of:
  Pass, Partial, Gap, or Not applicable (with a reason). Partial and Gap rows
  are read by scripts/check-rules-swift.sh as blockers, so they keep the gate
  red until resolved. Cite evidence (a command and its output) for Pass rows.
-->

| Rule file | Applies | Status | Evidence or gap |
|---|---:|---|---|
| `core/no-shortcuts-first-principles.md` | yes | Pass | `scripts/check-rules-swift.sh` greps `Sources/` and `Tests/` for shortcut patterns |
| `namespacing.md` | yes | Pass | `scripts/check-namespacing.sh`: one public type per file under `PureXML` |
| `package-architecture.md` | yes | Pass | target/test-target pairing enforced in `scripts/check-rules-swift.sh` |
| `package-structure.md` | yes | Pass | root `Package.swift`, root `Sources/`, root `Tests/` |
| `cross-platform.md` | yes | Pass | macOS, Linux, Windows, WASI build workflows under `.github/workflows/` |
| `validation-rules.md` | yes | Pass | `scripts/check-validation-coverage.sh` over the coverage registry |
| `framework-policy.md` | yes | Pass | banned-stack octal scan in `scripts/check-rules-swift.sh` |
| `testing.md` | yes | Pass | parser, emitter, schema, and W3C conformance suites under `Tests/` |
| `documentation.md` | yes | Gap | DocC coverage not yet audited |
| `ui/*` | no | Not applicable | headless library, no UI layer |
| `exp/package-swift.md` | no | Not applicable | single-target package, no exp closure manifest |

## Required Remediation

1. Audit DocC coverage against `documentation.md` and resolve the `documentation`
   row.
2. The public leak gate (`scripts/leak-gate.sh`) flags the repo's pre-existing
   Antigravity onboarding content (`GEMINI.md`, `docs/onboarding-antigravity.md`,
   and the Antigravity references in `AGENTS.md`). These are owner-managed and
   out of scope for this additive adoption; resolve with the maintainer whether
   to whitelist them in the gate or relocate the content.
3. Repoint the two remaining `docs/rules/` links in
   `docs/onboarding-antigravity.md` (owner-managed) to `third_party/rules-swift/`
   and `docs/research-first.md`.

Until those items are complete, state the honest status: PureXML has strict rule
enforcement wired in, and that enforcement correctly fails while the repo does
not yet fully conform to the entire `rules-swift` corpus.