PureXML/third_party/rules-swift/CHANGELOG.md

# Changelog

All notable changes to this rule set are documented here. This project follows Semantic Versioning.

## [Unreleased]

## [2.14.0] - 2026-11-02

### Changed

- `concurrency.md`: where a synchronous API must guard shared state (a protocol requirement, a synchronous engine), the rule now names `Synchronization.Mutex` (SE-0433) beside `actor`: it is `Sendable` without `@unchecked`, and the state is reachable only inside `withLock`. The gate's escape-hatch and `NSLock` checks are unchanged.

## [2.13.0] - 2026-10-31

### Changed

- `ui/flowspec.md`: the verb list now includes `ambient` and `rotate`, the engine is described with `AsyncStepRegistry` and `AsyncScenarioRunner` for an async pre-UI door, and a new DO says to load hand-edited scenarios with `ScenarioLoader.loadValidated`.
- `ui/flowspec.md`, `ui/pom.md`, `README.md`: the FlowSpec link points at its Codeberg home, `https://codeberg.org/Mihaela/FlowSpec`, instead of GitHub, where it no longer lives.

## [2.12.0] - 2026-10-28

### Added

- `ui/pane-layout.md`: a section on one set of panes on a Mac, an iPad and an iPhone with SuperSplit, ten rules: one view per pane role with many containers (a phone gets the same views as pages, not a split); the arrangement is a value that names the saved layout; a pane's share and its least size are different limits and the least wins; the Mac hides the problem by being wide, so test every pane at its least width; the divider is the edge of a pane and its frame in the accessibility tree is what a test asserts against; the card's clip loses what does not fit, so pair it with a test and a picture; maximize is the way to give one pane the whole area; a platform view needs an owner that lives as long as the pane; chrome as glass is a background; and three levels of test (the pure layout, the real window's frames, a picture of each arrangement).

## [2.11.0] - 2026-10-28

### Added

- `ui/pane-layout.md`: eight rules from an iPad and an iPhone Duo with a real editor, each a defect that shipped: the split sizes a pane and the content does not; an optional part is decided by a measurement (a tip in `ViewThatFits` widened a 240 point pane to 296); a header fits the narrowest pane; columns are decided by the room the parts need and not by a fixed 1000 points (a 13 inch iPad upright is 1032); a layout is saved for each way the device is held; the whole area for the document; a platform view is updated by its inputs and keeps its controller; and a picture of each arrangement is a deliverable. With two acceptance commands.
- `iphone-duo.md`: a section of what was observed on the simulator, kept apart from what Apple documents: a vertical toolbar over a vertical tab bar on the closed display, a fold that rebuilt the navigation and lost the screen, and the tools that work (Device Hub only; screenshots are black unless closed).

## [2.10.0] - 2026-10-28

### Changed

- `iphone-duo.md`: availability is now stated from the SDK's own Swift interface and headers, with two facts the Apple pages do not carry (the macOS SDK of Xcode 27.1 is 27.0 and lacks the 27.1 symbols; members of a type listed for a platform can be unavailable there, as `horizontalOnly`, `verticalPreferred`, `ToolbarOverflowMenu` and the compression behaviors are on macOS), the per-API versions of the bar APIs are corrected (`visibilityPriority` iOS 27.0 and macOS 26.1, `ToolbarOverflowMenu` iOS 27.0), and a new rule says the newer APIs are reached through one layer that checks the SDK and the OS separately and gives each a fallback (the `Forwards` package).

## [2.9.0] - 2026-10-28

### Added

- `iphone-duo.md`: the foldable iPhone, from Apple's own pages (the Human Interface Guidelines page, the
  documentation of Preparing your app for iPhone Duo, ArrangementView and reserved regions, five Tech Talks
  and the WWDC26 UIKit session; none is in the Cupertino corpus yet). The app is resized by a fold while it
  runs, so: the size is read on every change from the view and never from the screen or the launch; layout
  is decided by size classes and the space, not by idiom, orientation or `UIScreen.main`; state lives above
  anything a size class swaps; reserved regions, arrangement views and the hinge are iOS 27.1 and used in
  their places (regions and arrangements for layout, the hinge for effects); the system's bars carry the
  controls; safe areas are not symmetric; a second window is a request that can fail; and every pose and
  every change between poses is tested. States what Apple has not documented (the transition, state across
  a fold, scene behavior on a fold, sizes), and that the claim of support is made only after the transition
  test has been run.

## [2.8.0] - 2026-10-28

### Changed

- `accessibility.md`: the Mac is audited too, and what it found is in the rules (a divider with no role is a slider on the Mac and an adjustable action on iOS; a list, an outline and a placeholder-only text field are named; a ruler beside text is hidden). A finding is checked against the pixels of the picture before it is listed, and one the pixels contradict is recorded as a false positive with its measured ratio. The ledger may name element kinds, a finding with no element is let pass only by an entry with no label, and the macOS SDK's missing audit types are named by their raw values. Rule 14 now has a built answer (pages instead of columns at accessibility sizes, decided by a tested pure function) and says for which screens it was looked at.

## [2.7.0] - 2026-10-27

### Added

- `accessibility.md`: text through text styles (Dynamic Type) with the app's own zoom applied as a shift of it,
  every control named by what it does and never by its symbol's default name, 28 point tap targets, an
  alternative for every gesture (named actions, adjustable elements), the name and actions on the element a
  person reaches and not on a container, contrast as arithmetic (4.5 to 1, Light, Dark, Increase Contrast),
  announcements, Reduce Motion, layer-drawn UI exposed element by element, and a UI framework's core that
  describes while each surface must declare that it realizes it. The audit
  (`performAccessibilityAudit`) runs in UI tests and fails for a finding that is not on a ledger of known
  findings, each with its reason. Written from the Cupertino corpus (the Human Interface Guidelines pages
  Accessibility and VoiceOver, Performing accessibility testing, the audit's documentation) and from what the
  audit measured on an iPad app: 300 findings on five screens, 118 of them hit areas, 69 Dynamic Type, 59
  contrast. States what is not established: the layout at the largest accessibility size, VoiceOver on a
  device, and the audit on the Mac.

## [2.6.0] - 2026-10-27

### Added

- `help.md`: an app's help is written once, in one JSON file, and every platform's help is made from it. The
  Mac carries an Apple Help Book (the two Info.plist keys, the book's structure and indexes, generated and
  checked against the file) and leaves the Help menu to the system; an iPad and an iPhone have an in-app
  help sheet in a Help menu of the toolbar and in the menu bar of an iPad, and the version in the Settings
  app through a Settings bundle; tips (TipKit) point at the first thing to do and go when it is done. Each
  platform is told in its own words. Ships a build-checked acceptance list and tests; what was observed on a
  built app is stated as observed, and the Help Book format, which the Cupertino corpus does not hold, is
  marked as such.

### Changed

- `versioning.md` rule 14: the stamp phase names the built `Info.plist` as an input file, so that it runs
  after the system writes the plist; observed on a clean build, where the stamp was lost without it.

## [2.5.0] - 2026-10-18

### Added

- `app-logging.md`: every shipped app has one given recorder, entries that are facts and never the
  person's content, every intent and state change logged, a Developer menu in Debug and Beta builds
  only, and a report (log window, snapshot, optional content) made on the person's request and
  sent only by their choice. Ships a build-checked acceptance list and tests.
- `crash-and-state-reporting.md`: MetricKit and StateReporting used behind `canImport` and
  availability, the system's crash reports as a second door, one crash seen through both doors
  kept once, the call stack never in the log, states joined to the log. Claims about delivery and
  the return of states are stated at the strength they were shown.
- `versioning.md` rule 14: the stamp in an Xcode app target is a post-build script phase.

## [2.4.0] - 2026-10-17

### Added

- `versioning.md`: the version is written once, in a `VERSION` file, and read as Semantic
  Versioning 2.0.0 (a value outside the grammar stops the build); the store's short version is
  the core only; the build number is the first-parent commit count of the release branch, which
  grows by one per commit, never restarts, and names one commit; both reach the code through a
  generated file from a build-tool plugin whose command names its inputs (`VERSION` and the
  git `HEAD` files); a shallow clone or a missing history is refused, never defaulted to `1`;
  CI fetches full history; release history is append-only; a store build comes from the release
  branch with a clean tree; a second upload of one commit needs its own number (the dotted
  form is stated as not established until one upload orders it). Each rule names its basis as
  documented, observed, or design. Ships six acceptance commands and the tests, including a
  regeneration check in a throwaway clone.

## [2.3.0] - 2026-10-14

### Added

- `app-intents.md`: App Intents live in one adapter target; an intent in a package is
  declared by an `AppIntentsPackage` that each app and extension includes; dependencies are
  registered, not passed; every string a person sees is a localized resource that names the
  package bundle and is handed to the system unresolved, so Siri and Shortcuts resolve it in
  their own language; an interpolated sentence keeps its plural forms (one and other in
  English and German, one, few and other in Croatian); a sentence is one key, not translated
  fragments. Each rule names its basis as documented or observed. Ships five acceptance
  commands, a test recipe for the languages (set `locale` on a copy of the resource, because
  `String(localized:bundle:locale:)` reads the process's language), and the statement that a
  unit test does not prove Shortcuts lists the intent in each language.

## [2.2.0] - 2026-10-14

### Added

- `ui/appuikit.md`: imperative AppKit and UIKit renderers, features, and app shells import
  the cross-framework layer and name its `AppUI*` types, never an `NS` or `UI` type or a
  direct SDK import; a missing alias or helper is added to the layer first. Ships an
  acceptance check (two greps to promote to a self-tested gate). `appkit-views.md` and
  `uikit-views.md` point to it.

## [2.1.1] - 2026-10-11

### Fixed

- `exp/common-mistakes.md`: the test-target pairing command filtered `swift package
  describe` output on the target type `regular`, which that output never uses (it says
  `library`), so the command checked no library target and passed vacuously. It now selects
  `library` and `executable`, and the rule says how to confirm the command selects
  something.

## [2.1.0] - 2026-10-11

### Added

- `testing.md`: an exception to "mocks live in the test target" for test-support
  targets that several test targets share, because SwiftPM does not let a test target
  depend on another. It names four conditions (declared in a checked-in table, not
  published, not shipped except by a named allowlist, mechanically checked) and ships a
  runnable acceptance check.

## [2.0.0] - 2026-07-11

### Added

- A complete local repository gate covering leak, namespacing, filenames,
  relative links, rule structure, changelog, version bumps, and fault injection.
- A checked-in five-label tracker manifest plus scheduled issue-body and label-drift
  auditing against Codeberg.
- An exact vendored core license, allowing the upstream README and every changed
  core rule to remain byte-identical after synchronization.
- A byte-for-byte core-sync gate with a planted divergent-vendor negative control.
- Negative controls for commit-message rejection, breaking-change notation,
  missing Markdown links, leaked prose, namespacing violations, missing rule proof
  sections, missing changelog/version bumps, stale issue bodies, label drift, and
  consumer freshness.
- Acceptance checks for the remaining binding parsing, namespacing, planning,
  design, dependency-injection, migration, and package-testing rules.

### Changed

- **Breaking:** Renamed the non-conventional `CONVENTIONS.md` overview to
  `conventions.md`; inbound repository links now use the lowercase path.
- **Breaking:** Reconciled the target graph, DI seams, namespace exception,
  protocol-creation threshold, test-framework scope, and dependency direction
  into one non-contradictory architecture. Consumers must review these rules
  before updating their freshness marker.

### Fixed

- Made forbidden-byte matching portable across POSIX shells so Linux `sh` does
  not treat hexadecimal escape text inside the gates as a leak.
- Replaced the unavailable hosted priority-label action with a repository-owned
  Forgejo API script and deterministic add, remove, and no-op fixtures.
- Renamed the consumer workflow from conformance to freshness so its name matches
  its actual proof: it compares the shared-rules version marker and does not claim
  semantic conformance.
- Strengthened the commit hook to enforce Conventional Commit types, the 72-column
  limit, automated-author attribution prohibitions, and the em-dash rule.
- Made missing SwiftFormat or SwiftLint fail instead of silently weakening a commit
  that contains Swift files.
- Repaired stale repository-relative links and narrowed the shared-path exception
  in the folder-grouping rule so it no longer contradicts the default mandate.
- Scoped the Apple framework policy to Apple client/UI targets so it no longer
  contradicts the Swift Linux, Windows, WASM, and server rules.
- Normalized ExtremePackaging terminology and examples to the repository's
  one-package/many-targets architecture, removing impossible nested manifests.
- Classified the repository's `VERSION` marker as a conventional root filename and
  repaired the file-naming rule's non-Conventional commit example.
- Removed the dead GitHub workflow badge and documented the Forgejo fallback and
  local source of verification evidence.
- Moved the shell-only consumer freshness job from an unproven `macos` label to
  the repository's demonstrated `ubuntu-latest` Forgejo runner label.
- Flattened the sole consumer workflow template from the one-file `templates/`
  directory to `rules-freshness.yml` at the repository root.

## [1.1.2]

- **scripts/leak-gate.sh (.build exclusion):** all three scans and the file count now
  exclude `.build/` directories. Fetched dependency checkouts carry their own vendor
  names, absolute-path examples, and em dashes in documentation the repo does not own
  and git does not track; scanning them made the gate permanently red on any consumer
  with resolved dependencies, which trains readers to ignore it. Found by a rule-canon
  audit on 2026-07-04 where the gate failed consumers solely on `.build/checkouts/`
  markdown.

## [1.1.1]

- **scripts/leak-gate.sh (charter-file exception):** the vendor-name scan now excludes the
  two agent charter files at the repository ROOT, where the filename is the tool's
  addressing interface (function, not attribution). Root only; the same name in any nested
  file still fails, and the exception is fault-injection tested downstream. A permanently
  red gate trains readers to ignore it, which is worse than no gate.

## [1.1.0]

- **documentation.md Rule 0 (DocC scope):** DocC is packages-only (never apps), and only
  for packages that are public OR heavily used. Non-qualifying packages skip the DocC
  catalog entirely. Narrows the former "every project" framing.

A conformance pass brought the repository closer to agreement with its own rules.

### Added

- Vendored `core/oracle-first.md` from the engineering-discipline upstream: build the answer key (Oracle, comparison law, failure report, unsupported-case classification, parity gate) before any system or new correctness surface, including the "a codified expectation is a witness, not a verdict" guidance. Indexed in `core/README.md` and the README core-spine list.
- Acceptance check sections for the rule files that lacked one (per `core/rules.md`): `core/first-principles-analysis`, `core/systematic-debugging`, `concurrency`, `linux-server`, `ui/native-per-platform`, and the ExtremePackaging set (`exp/build-performance`, `exp/common-mistakes`, `exp/critical-rules`, `exp/dependency-management`, `exp/implementation-patterns`, `exp/package-swift`).
- Namespacing gate `scripts/check-namespacing.sh` (one non-private top-level type per file, per `code-style.md`), wired into the `pre-commit` hook and the gates CI workflow.
- GitHub issue forms (feature, bug) with required status/priority/complexity fields, a pull-request template, and an issue-priority labeler workflow, per `core/git-discipline.md`.
- README CI and license badges, and a License section.

### Fixed

- Broken cross-reference links in `CONVENTIONS.md` and `code-style.md`.

### Changed

- Label set trimmed to the brutal-minimum per `core/git-discipline.md` (added `epic` and `priority: high`; removed the decorative stock labels), with the Rule 2.3 semantic color palette.
- Synced the vendored core spine to the engineering-discipline upstream: `core/systematic-debugging.md` gains "Rule 6: Debugging against a differential or parity oracle" and two anti-patterns; `core/verification.md` and `core/git-discipline.md` gain the GitHub-hosted vs self-hosted CI runner escalation rule; `core/testing-discipline.md` gains the hosted-first runner note; `core/proof-discipline.md` and `core/no-shortcuts-first-principles.md` gain `oracle-first.md` cross-references. The local acceptance-check sections in `core/first-principles-analysis.md` and `core/systematic-debugging.md` are preserved.

## [1.0.0] - 2026-06-15

Initial public release of the Swift domain rules, built on the engineering-discipline core spine (vendored in `core/`).

### Added

- Where an app starts: `business-rules-and-constraints` (MANDATORY first artifact: business rules as explicit checkable statements, plus the constraints that bound them, which REST services, what compliance, which auth model) and `domain-first` (MANDATORY: start at the domain and business rules, framework-free and headless-provable; the UI framework is the last, reversible, and plural choice).
- Swift craft: `code-style`, `namespacing`, `dependency-injection`, `concurrency`, `cross-platform`, `linux-server`, `testing`, `formatting-and-linting`, `documentation`, `documentation-search`, `package-structure`, `package-architecture`, `package-import-contract`, `shared-protocols`.
- UI (`ui/`): `pre-ui-layer` (the display-less model seam, MANDATORY: Domain + Surface, one `perform(Intent)` channel, renderers the only UI import; one model drives the SwiftUI, AppKit, and UIKit renderers at once, both the architecture's payoff and a comparison instrument), `pom` (Page Object Model for UI tests), `flowspec` (declarative UI scenarios via the [FlowSpec](https://github.com/mihaelamj/FlowSpec) package), plus three renderers over the one model (`swiftui-views`, `uikit-views`, `appkit-views`), `view-models`, `components`, `colors`, `fonts`.
- Parsing and validation: `parsing-rules` and `validation-rules` (the OpenAPIKit idiom). Validation requires every public type to be validated or excluded with a reason, enforced mechanically.
- Apple-platform stance: `framework-policy` (Apple-only mandate), `openapi-generated`.
- Drop-in kit: `.gitignore`, `.swiftformat`, `.swiftlint.yml`, `.pre-commit-config.yaml`, and `.githooks/` (a `pre-commit` format-and-lint hook and a `commit-msg` attribution/em-dash check).
- Vendored `core/` spine: the cross-cutting engineering-discipline rules (incl. `round-trip-transformation`).
- Dual license: prose under CC BY 4.0, code under MIT.