@mmerterden/multi-agent-pipeline 13.0.0 → 13.2.0

package/pipeline/skills/shared/external/ios-coding-standard/references/rules.yml

@@ -0,0 +1,1163 @@
+version: 1.0.0
+updated: 2026-07-26
+owner: iOS platform
+description: >
+  The rule registry. STANDARD.md teaches these to a newcomer with examples; SKILL.md audits
+  against them. IDs are stable and never renumbered — a rule is retired by status, not deletion.
+severity_levels: [blocking, important, suggestion]
+enforcement_kinds:
+  format: the formatter owns it; not reviewed by humans
+  lint: a linter decides it mechanically
+  scan: a tool measures it (dead code, coverage, graph)
+  judgement: requires a human or an audit run
+exception_marker: "// standard:exception(<RULE-ID>) <reason> <expiry:YYYY-MM-DD>"
+
+persistence_decision:
+  description: >
+    Answer this BEFORE reaching for storage. Keychain is the answer to "where does a persisted
+    secret live", not to "this value is sensitive". Most sensitive values in a flow never need to
+    persist at all, and persisting them is the more expensive mistake.
+  ladder:
+    - step: 1
+      question: Does this value need to outlive the current flow?
+      default: "No — assume transient until a requirement says otherwise"
+      if_no: >
+        Keep it in memory for the duration of the flow and drop it when the flow ends. Do NOT
+        write it to the Keychain: an unnecessary keychain item survives the flow, survives logout
+        unless someone remembers to delete it, and creates a cleanup obligation nobody owns.
+        Over-persisting is itself a finding, not a safe default.
+      if_yes: go to step 2
+    - step: 2
+      question: What does it need to survive — app backgrounding, app restart, or reinstall?
+      guidance: >
+        Backgrounding only -> in-memory state owned by the flow's model is still correct.
+        App restart -> Keychain with the accessibility class the data demands.
+        Reinstall -> a deliberate product decision that someone signs off; never a storage default.
+    - step: 3
+      question: Which data class is it?
+      guidance: >
+        The class (below) decides the storage tier and the logging rule. never-persist-locally
+        classes stay transient no matter what step 2 said — the answer to "it needs to survive"
+        for a payment instrument or a biometric is a server-side or system-provided token, not
+        local storage.
+  transient_obligations: >
+    Transient does not mean unregulated. A value held only in memory still obeys SEC-03 (never
+    logged), SEC-05 (cleared when the flow ends or the session drops, hidden from the app-switcher
+    snapshot), and SEC-06 (never sent to analytics).
+
+sensitive_data_classes:
+  description: >
+    The SEC rules are written against these CLASSES, never against one module's field names.
+    Each audited module resolves its own concrete instances into a sensitive-data inventory
+    (SKILL.md Phase 2d), and the lint mechanisms are generated from that inventory rather than
+    hardcoded. A class with no instance in the module simply yields no rule.
+    The at_rest value below applies ONLY to values that passed the persistence ladder — it says
+    where a value goes IF it must persist, never that it must.
+  classes:
+    - id: auth-token
+      covers: session, access, refresh and bearer tokens; loyalty or membership auth tokens; API credentials
+      at_rest: keychain-required
+      loggable: never
+    - id: credential
+      covers: password, PIN, passcode, security answer, one-time code
+      at_rest: keychain-required
+      loggable: never
+      note: prefer never persisting at all; a one-time code has no reason to outlive its use
+    - id: government-id
+      covers: national identity number, tax number, driving licence number
+      at_rest: keychain-required
+      loggable: never
+    - id: travel-document
+      covers: passport number and expiry, visa data, residence permit
+      at_rest: keychain-required
+      loggable: never
+    - id: booking-reference
+      covers: reservation code, ticket number, boarding pass payload, barcode data
+      at_rest: keychain-or-protected
+      loggable: never
+      note: individually low-value, but it authorises access to a passenger record
+    - id: membership-identity
+      covers: loyalty or programme membership number, tier, account identifier
+      at_rest: keychain-or-protected
+      loggable: hashed-or-truncated-only
+    - id: payment-instrument
+      covers: card number, expiry, CVV, tokenised card reference, billing address
+      at_rest: never-persist-locally
+      loggable: never
+    - id: personal-contact
+      covers: full name, date of birth, email, phone, postal address
+      at_rest: protected-storage
+      loggable: never
+      note: name alone is low risk; name paired with date of birth or a document number is not
+    - id: biometric-or-health
+      covers: any biometric template, health or accessibility need, special-category data
+      at_rest: never-persist-locally
+      loggable: never
+    - id: precise-location
+      covers: device coordinates beyond city granularity
+      at_rest: never-persist-locally
+      loggable: never
+
+rules:
+
+  # ── READ — format & readability ───────────────────────────────────────────
+  - id: READ-01
+    title: MARK sections separate concerns — business rules, service calls, UI, one group each
+    severity: important
+    enforcement: judgement
+    rationale: readability
+    check: >
+      A file mixing a service call, a business rule and a view fragment under one MARK (or none)
+      is a finding even when short. Section order follows the module's conventions doc.
+      In a use case or repository implementation the sections are named after WHAT EACH TALKS TO
+      — `Service requests`, `On-device cache`, and so on — so a reader sees at a glance which
+      calls leave the device and which do not.
+
+  - id: READ-02
+    title: Comments are clear statements; no AI or tool attribution anywhere
+    severity: blocking
+    enforcement: lint
+    mechanism: 'custom regex: (?i)(generated by|copilot|co-authored-by:.*(claude|anthropic|ai))'
+    rationale: readability
+    check: >
+      Trim a comment by deleting what the code already says, the design-frame archaeology and the
+      historical aside — never the decision. If a sentence records WHY a shape was chosen, or what
+      breaks without it, it stays however long the block ends up.
+
+      Carve-out — a comment that IS data is not prose and is not trimmed: a trigger/prefix table,
+      a state-transition matrix, a wire-contract enumeration. Those exist nowhere else in the
+      codebase, so shortening them destroys the only copy. Judge a long block by whether it
+      repeats the code or replaces a missing document.
+
+  - id: READ-03
+    title: Size thresholds with carve-outs — screen 600 / file 400 / function 40 lines
+    severity: important
+    enforcement: lint
+    mechanism: swiftlint file_length, function_body_length, type_body_length
+    rationale: readability
+    exempt: [generated sources, mock/fixture data files]
+    tooling_limitation: >
+      SwiftLint's built-in length rules take no per-rule `excluded`, so the mock/fixture carve-out
+      cannot be expressed in the config — those files still report. Honour the exemption in the
+      audit pass and in the baseline; do not "fix" a fixture file to satisfy a line count.
+    check: File over 120 lines with zero MARK is a separate finding — a reader has no map.
+
+  - id: READ-04
+    title: Component placement is decided by call-site count, not by feel
+    severity: important
+    enforcement: judgement
+    rationale: readability
+    check: >
+      2+ call sites -> own file with its own configuration in the shared layer. Exactly one call
+      site and bound to the screen's state -> private view builder in a MARK'd extension.
+      Both directions are findings.
+
+  - id: READ-04e
+    title: Header chrome belongs to the header, not to the scroll content
+    severity: suggestion
+    enforcement: judgement
+    rationale: readability
+    check: >
+      A bar that reads as part of the screen's header — a route chip, a countdown, a step bar —
+      goes inside the header component's add-on slot, not as the first row of the scroll
+      content. Rendered below the header it squares off the header's rounded bottom corners and
+      scrolls away from the title it belongs to. The header component has the slot; use it.
+
+  - id: READ-04b
+    title: A view fragment that renders a thing is a component file with a preview
+    severity: important
+    enforcement: judgement
+    rationale: testability
+    check: >
+      A `private var x: some View` inside a scene is a component in disguise. If it renders a
+      THING — a switcher, a chip row, a banner, a bar, a legend, a card — extract it to its own
+      file under the screen's `Presentation/Components/`, as a `struct` that takes DATA and
+      CALLBACKS, never the view model, and give it a `#Preview`.
+      Taking data instead of the view model is what makes the preview possible at all: a
+      component holding a view model needs the DI container a canvas preview never configures,
+      and the workaround (a preview-only fixture type shipped in production sources) is itself
+      a finding.
+      What stays a `@ViewBuilder` on the scene: the composition itself — the piece that orders
+      the components, branches on loaded / error / empty, and reads the view model to decide
+      WHICH component shows. That is business-rule display and it belongs with the screen.
+      The test is what the fragment DOES, not how long it is. A row of icon + two labels + a
+      button is a component even at ten lines; a three-line `if loaded { a } else { b }` is
+      composition. A fragment that renders a thing AND takes no parameters is still a component —
+      "it needs no arguments" means the data is hardcoded or read off the view model, and both
+      are reasons to extract, not to keep it.
+      A component the design system already owns (the shared UI package) needs no wrapper and
+      no preview here; render it inline and let the design system own its previews.
+
+  - id: READ-04c
+    title: A business rule is a view-model member; the view reads it, never computes it
+    severity: important
+    enforcement: judgement
+    rationale: testability
+    check: >
+      A `private var x: Bool/String/Int` in a scene that reads the view model and decides
+      something — "is the header shown", "which leg is active", "what does the CTA say" — is a
+      business rule in the view layer. It belongs on the view model, in its business-rules
+      section, where a unit test can reach it. The scene reads `viewModel.x`.
+      Not this rule: building a design-system `Configuration` value. Moving those to the view
+      model drags UI types across the boundary; they belong inside the component that renders
+      them (READ-04b), which is where they disappear once the component takes data.
+
+  - id: READ-04d
+    title: A pure transform is a shared helper, not a method on the view
+    severity: important
+    enforcement: judgement
+    rationale: flexibility
+    check: >
+      A function in a scene that touches no view-model state and returns no view — a date
+      format, a duration split, initials from a name, a unit conversion — is a value transform.
+      It belongs in the module's formatter / extension home (`Common/Formatters`, a typed
+      `X+Extension`), not on whichever screen needed it first.
+      The tell is duplication: the same `initials(_:)` written once in a scene and again in a
+      mapper is the normal outcome of leaving these where they were typed. Move it on the first
+      sighting, not the second.
+      **A domain-local formatter type is the second choice, not the first.** Search the shared
+      layer BEFORE writing one: a date/number/string transform with no domain vocabulary in it
+      is not a domain concern, and the app already has a home for it (`CoreExtensions`,
+      `CoreFormatters`). Grep the behaviour, not the name — the existing helper will be spelled
+      differently (`Date.localizedBFFDate` vs a hand-rolled `displayDate`), and a per-domain
+      `XFormatters` full of re-implementations of it is how three domains end up with three
+      subtly different renderings of one contract field. When the shared helper is 90% right,
+      extend IT (a new `Format` case, a defaulted parameter) rather than forking it.
+      A domain-local formatter type is correct only when it adds domain vocabulary on top of the
+      shared primitives — naming which two formats a screen's pickers exchange, for instance —
+      and implements no formatting of its own.
+      Not this rule: a function that builds a design-system `Configuration` from screen data.
+      That is the component's own lowering and belongs inside the component (READ-04b).
+
+  - id: READ-05
+    title: Multi-line signature style — open paren at line end, one parameter per line
+    severity: suggestion
+    enforcement: format
+    mechanism: swiftformat wrapArguments
+    rationale: readability
+
+  - id: READ-06
+    title: One extension per protocol conformance
+    severity: suggestion
+    enforcement: judgement
+    rationale: readability
+
+  - id: READ-07
+    title: Casing, boolean prefixes, guard-early / return-early
+    severity: suggestion
+    enforcement: lint
+    mechanism: swiftlint identifier_name, type_name, cyclomatic_complexity
+    rationale: readability
+
+  - id: READ-08
+    title: Forbidden constructs — force unwrap, force cast, IUO, magic numbers, raw colors/fonts, print
+    severity: blocking
+    enforcement: lint
+    mechanism: swiftlint force_unwrapping, force_cast, force_try, implicitly_unwrapped_optional; custom no_print, no_raw_hex, no_raw_font
+    rationale: security
+
+  - id: READ-09
+    title: Standard file header — own target module, and the author's FULL git identity
+    check: >
+      The author line carries the identity exactly as git records it, department included
+      ("NAME - <Department> Mudurlugu"). A bare name does not say which team owns the file, and
+      the same person appears under several spellings once the department is dropped.
+    severity: suggestion
+    enforcement: lint
+    mechanism: swiftlint file_header
+    rationale: readability
+
+  # ── STRUCT — project structure ────────────────────────────────────────────
+  - id: STRUCT-01
+    title: One primary top-level type per file; nesting only for owned details
+    severity: important
+    enforcement: judgement
+    rationale: readability
+    check: >
+      Forbidden nested: entity, domain model, request/response payload, list element. Allowed
+      nested: a configuration/style/state helper with exactly one owner and no second reference
+      site; a nested type a MACRO or an external design mapping owns — a `@FormSection`-generated
+      `X.Section`, a Code Connect-mapped `X.State` — where flattening silently renames a
+      contract the generator or the design file still refers to (the compiler catches the macro
+      case, the design mapping fails silently); and a pure constants namespace — a caseless enum
+      whose members are only `static let`
+      literals (`AppConstant.Phone.defaultDialCode`), where the nesting IS the grouping and
+      flattening to `AppConstantPhone` buys nothing. Decide by reference count, never by keyword.
+
+  - id: STRUCT-02
+    title: A screen is a known file manifest, not a pile
+    severity: important
+    enforcement: judgement
+    rationale: readability
+    check: >
+      Scene, ViewModel, LocalizedText, CoordinatorEvent, AnalyticsTracking, UseCase, Repository
+      (+protocol +mock), Mapper + models — each present when its responsibility exists. Report a
+      missing file whose responsibility leaked elsewhere AND a ceremonial empty file.
+
+  - id: STRUCT-03
+    title: Every screen sits at the same depth with the same internal grouping
+    severity: important
+    enforcement: judgement
+    rationale: readability
+
+  - id: STRUCT-04
+    title: Nothing lives outside the layout — no loose root type, no Utils/Helpers/Misc bucket
+    severity: important
+    enforcement: judgement
+    rationale: readability
+
+  - id: STRUCT-05
+    title: Type placement follows a consumer-count ladder
+    severity: important
+    enforcement: judgement
+    rationale: flexibility
+    check: >
+      2+ modules -> cross-module shared tier. 2+ screens -> module shared entities. One screen ->
+      that screen's own domain folder, in the sub-folder its KIND belongs to: an enum in
+      `Domain/Enums/`, a value object in `Domain/Entities/`. A screen-behaviour enum (NAME-05) is
+      a domain type, not a presentation one — it does not live beside the Scene.
+      Both over- and under-hoisting are findings: a single-consumer type in the shared tier
+      inflates the shared surface and reads as load-bearing when it is not.
+
+  # ── NAME ──────────────────────────────────────────────────────────────────
+  - id: NAME-01
+    title: One name per role — the navigation handler is never called something else
+    severity: blocking
+    enforcement: lint
+    mechanism: 'custom regex scoped to Scene/ViewModel: \boutput\b as a handler property or parameter'
+    rationale: readability
+
+  - id: NAME-02
+    title: Our models use RequestModel/ResponseModel; transport suffixes stop at the data layer
+    severity: blocking
+    enforcement: lint
+    mechanism: 'custom regex: Dto\b in Presentation paths'
+    rationale: flexibility
+
+  - id: NAME-03
+    title: Module naming scheme — forbidden affixes come from the module's own conventions doc
+    severity: important
+    enforcement: lint
+    mechanism: custom regex per module (Fetch prefix, Flow suffix, Manager/Helper/Util where banned)
+    rationale: readability
+
+  - id: NAME-04
+    title: Fixed value sets are enums with tolerant decoding, not raw strings
+    severity: blocking
+    enforcement: judgement
+    rationale: security
+    check: >
+      An unrecognised server value must land on a known-unknown case rather than failing or
+      silently carrying an arbitrary string into the UI.
+
+  - id: NAME-05
+    title: Screen behaviour is driven by an enum state, not by a spread of booleans
+    severity: important
+    enforcement: judgement
+    rationale: readability
+    check: >
+      Where the wire already carries the state (a status, a redirect, a form type), map it into
+      an enum and branch on that — NAME-04 covers the decoding side. Where it does not, but the
+      screen still renders materially different variants, declare the enum ON THE SCREEN and
+      derive it from whatever inputs decide it. A variant set spread across three or four
+      independent booleans is the finding: nothing states which combinations are legal, the
+      reader has to enumerate them by hand, and `switch` stops telling the compiler to check
+      exhaustiveness.
+
+      Two shapes qualify as a finding:
+      1. Three or more booleans read together to decide one visual outcome.
+      2. A boolean pair whose illegal combination is only prevented by call order.
+
+      The enum belongs to the view model as a derived value, not to stored state — deriving it
+      keeps a single source of truth, whereas a stored copy drifts from the inputs it mirrors.
+      Two independent booleans that never interact are fine; do not enum-ify for its own sake.
+
+  - id: STRUCT-07
+    title: A scene is one type — no inner view struct wrapping it
+    severity: important
+    enforcement: judgement
+    rationale: readability
+    check: >
+      `struct XScene: View { var body: some View { XView(viewModel: viewModel) } }` with the real
+      body in a second struct in the same file is two types where the reader expects one: the
+      scene's name is the one in the coordinator and the file, and everything about the screen
+      should be under it. Fold the inner view's body and state into the scene. The exception is a
+      genuinely reusable view with its own consumers — and that one belongs in
+      `Presentation/Components/` under READ-04b, not beside the scene.
+
+  - id: STRUCT-08
+    title: Each live implementation sits in its own file beside its protocol
+    severity: important
+    enforcement: judgement
+    rationale: readability
+    check: >
+      `XUseCase.swift` holds the protocol; `XUseCaseLive.swift` sits next to it. Same for a
+      repository. A reader opening the protocol sees the contract without scrolling past an
+      implementation, and the implementation file is where the collaborators are declared.
+
+  - id: STRUCT-06
+    title: A validation rule is a shared type until measurement says otherwise
+    severity: important
+    enforcement: judgement
+    rationale: flexibility
+    check: >
+      Form/validation rules are the classic silent duplication: each one is small enough to
+      re-type in ten seconds, so every module does, and the copies then drift. Before adding one,
+      grep the shared rule library AND every sibling module for the CONCEPT, not the name — the
+      same rule appears as `EmailFormatRule` / `EmailRule`, `TCKNRule` / `TCKNChecksumRule` /
+      `NationalIdRule`, `PnrRule` / `PnrOrETicketFormatRule` / `<Screen>PnrOrETicketFormatRule`.
+      Name-matching alone finds none of those.
+
+      Placement follows STRUCT-05, with one addition: the error copy is NOT part of the rule.
+      A rule takes its error as an init parameter, so one shared implementation serves every
+      module while each keeps its own localized message — that is what makes hoisting cheap.
+
+      Report per concept: implementations · owning modules · whether the shared library already
+      has one · and any BEHAVIOURAL divergence between copies. Divergence outranks the
+      duplication itself: two same-named rules that accept different input mean a value valid on
+      one screen is rejected on another, and nothing in either module says so. Merging them is a
+      behaviour decision needing its own tests, never a silent move.
+
+  # ── SVC — service surface ─────────────────────────────────────────────────
+  - id: SVC-01
+    title: One request model in, one result out
+    severity: important
+    enforcement: judgement
+    rationale: readability
+    check: >
+      A boundary method past ~2 parameters is a finding — the parameters want to be a request
+      model. async, never a completion handler. No throws alongside the result family. Naming
+      is governed by SVC-07, which overrides "pick a domain verb" for anything that wraps a
+      single service call.
+
+  - id: SVC-02
+    title: Protocol, live implementation and test double share one signature
+    severity: important
+    enforcement: judgement
+    rationale: testability
+
+  - id: SVC-03
+    title: The call site reads as one awaited statement, handled in the data-loading section
+    severity: suggestion
+    enforcement: judgement
+    rationale: readability
+
+  - id: SVC-04
+    title: Generated networking is never hand-edited; generated types are touched only in the mapper
+    severity: blocking
+    enforcement: lint
+    mechanism: CI diff check on the generated path + custom regex for generated type names outside Mapper
+    rationale: flexibility
+
+  - id: SVC-05
+    title: One result and error family per module, built through one factory
+    severity: blocking
+    enforcement: judgement
+    rationale: testability
+
+  - id: SVC-06
+    title: Spec discipline — nothing hand-written around the generator, no endpoint in two specs
+    severity: important
+    enforcement: scan
+    rationale: flexibility
+
+  - id: SVC-07
+    title: A method that wraps one service call is named after that service
+    severity: important
+    enforcement: lint
+    mechanism: custom regex — non-`send` funcs in repository protocols surface for an explicit marker
+    rationale: readability
+    check: >
+      `send` + the endpoint path, segments in their own order, camel-cased, path parameters
+      dropped: `check-open-status` → `sendCheckOpenStatus`, `order/items/save` →
+      `sendOrderItemsSave`, `session/extend` → `sendSessionExtend`,
+      `lookup/{airlineAlliance}/airline` → `sendLookupAirline`.
+      The path is the name, not the generated client method. A generator prefixes GET
+      endpoints with `get` and appends parameter suffixes (`getSeatMapPageInfo`,
+      `getAirlineListByAirlineAlliance`) — both are artifacts of the generator, and `get`
+      also reorders the segments the backend chose. Copying the generated name silently
+      renames the service; copying the path keeps one spelling on both sides of the wire.
+      The HTTP verb is never part of the name: the endpoint already implies it, and `send`
+      already says a request leaves the device. The name
+      carries down the whole chain — repository protocol, live implementation, mock, test
+      double, and any use case that is a straight pass-through — so one grep from the
+      endpoint reaches every layer that touches it, and a reader of the call site knows
+      which service will fire without opening the repository.
+      Transport verbs invented by the client (`fetch…`, `load…`, `get…`) are the violation:
+      they name what the code does, which the signature already says, instead of what the
+      backend is being asked, which nothing else says.
+      Two exceptions, and both must be visible:
+      - **Several methods over one service.** When screen-scoped variants share a call
+        (three country pickers filtering one `lookup/country`; an OTP path and a no-OTP path
+        over one `add-fqtv-number`), the single private caller takes `send<ServiceName>` and
+        the variants keep their screen names above it.
+      - **No service behind it yet.** A placeholder whose endpoint does not exist keeps its
+        domain name.
+      Both carry `standard:exception(SVC-07)` with the reason, so the exception is a line in
+      the file rather than an inconsistency a reader has to explain to themselves.
+      A use case that aggregates, transforms, or merges sources is NOT a pass-through and
+      keeps its domain name (SVC-01).
+
+  - id: SVC-08
+    title: A business rule lives in the view model or on its own struct — nowhere else
+    severity: important
+    enforcement: lint
+    mechanism: custom regex — arithmetic and conditional expressions inside Mapper paths
+    rationale: testability
+    check: >
+      There are exactly two homes for a business rule: the **view model** that owns the
+      behaviour, or a **computed property on the struct the rule is about** (under a
+      `// MARK: - Derived`), when more than one screen asks the same question.
+      Every other layer is transport. A mapper, a `UseCaseLive`, a repository, a DTO mirror, a
+      coordinator, a data source — each moves values between two shapes and decides nothing. A
+      `UseCaseLive` in particular reads as a tempting home because it already knows the domain
+      vocabulary: it does not get one. Its body is call → map → return, plus cache read/write;
+      the moment it branches on a status code, merges two responses by a rule, or defaults a
+      value nobody can derive from the payload, that rule has been hidden from the view model
+      that lives with it and from every test that would have covered it.
+      A mapper lowers one shape onto another and nothing else. Unwrapping an optional wire
+      field to its empty value (`?? ""`, `?? false`, `?? []`) is lowering and is fine — the
+      domain type is non-optional and the wire type is not.
+      These are NOT lowering, and each one belongs to the view model (or, when several screens
+      share it, a named domain rule the view models call):
+      - **Arithmetic and unit conversion.** `TimeInterval(ms) / 1000`, a currency scale, a
+        percentage. Carry the wire value with its unit in the name (`sessionTimeoutMs`) and
+        convert where it is read.
+      - **A clamp or a threshold.** `max(0, remaining)`, `count > 1`, "negative means none".
+        A past deadline meaning "no countdown" is a product decision, not a cast.
+      - **Choosing a screen state.** Resolving a variant, an enum case, or an error message
+        from a combination of flags. Carry the flags; decide in the view model.
+      - **A policy default.** `?? 180` seconds, `?? passengers.count`. A number nobody can
+        derive from the payload is policy and belongs next to the code that lives with it.
+      - **Dropping or promoting records.** Filtering a code out of a list, or turning one code
+        into a different field, encodes what that code MEANS. That meaning belongs on the
+        entity when several screens read it, and in the view model when one does.
+      Why the mapper is the wrong home: it is the one type with no screen context, and a rule
+      buried in it is invisible from the view model that owns the behaviour, untestable without
+      constructing a DTO, and silently duplicated the next time another screen needs it.
+      A shape read the mapper legitimately makes: choosing which array element the requested
+      index refers to, or grouping rows by a key. It moves values into position; it does not
+      decide what they mean.
+      When the SAME lowering appears in more than one screen's mapper, it does not become a
+      shared mapper type in a folder of its own — it moves onto the entity it produces, as an
+      `init(_ dto:)` in an extension under a `// MARK: - Wire Mapping` in the entity's own file.
+      The entity is where a reader looks for "how is this built"; a `FooMapper` parked at the top
+      of the module is a second place to look and belongs to no screen.
+
+      **Moving a rule OUT of a mapper is two edits, not one.** The reason these rules survive
+      review is that deleting the decision also deletes the data it was computed from: the mapper
+      stored `isFailure: Bool` and dropped `info.status`, so no later layer can re-derive it.
+      So: first make the entity CARRY the raw inputs the decision reads (`info: Info?`,
+      `hasPrevention: Bool`, `apisCompletions: [Bool]`), then express the decision as a computed
+      property. Where that property lives:
+      - **On the entity**, under a `// MARK: - Derived` — when more than one screen, or the
+        screen AND its mocks, ask the same question. This is also what keeps the mock
+        repositories honest: a mock can no longer hand-set a state the real payload could never
+        produce, because the state is computed from the same inputs in both.
+      - **In the view model** — when the question is that one screen's, or when the answer needs
+        anything the entity does not hold (localized copy, a feature flag, live user state).
+      Never in the mapper, and never as a stored field the mapper fills, because a stored field
+      is indistinguishable from a wire value at every call site that reads it.
+
+      Auditing a module for this is a grep, but a noisy one. These MATCH the search and are NOT
+      violations — do not "fix" them: `init(x: T? = nil)` default-nil signatures, `?? ""` /
+      `?? false` / `?? []` lowering of an optional wire field onto a non-optional domain one,
+      `.first { $0.index == requested }` and `Dictionary(grouping:)` shape reads, and
+      `.filter { !$0.isEmpty }.joined()` name assembly. What IS a violation: a comparison that
+      names a code or a state (`== "TK"`, `== .error`, `status ?? "USABLE"`), a conditional that
+      emits or drops a field, an aggregation whose result is a screen state
+      (`contains { ... } ? .invalid : .valid`), and any localized string.
+
+  - id: PLAT-01
+    title: Platform affordances go through the app's own wrapper, not the OS API
+    severity: blocking
+    enforcement: lint
+    mechanism: custom regex — raw SwiftUI presentation APIs outside the shared wrapper's own module
+    rationale: flexibility
+    check: >
+      When the app ships a wrapper for a platform affordance — a sheet, a date picker, a toast —
+      a feature module calls the wrapper, never the OS API underneath. The wrapper exists
+      because the OS changed the affordance once already and will again: iOS 26 forced a
+      Liquid-Glass inset onto partial-detent sheets with no opt-out, which put a gap down the
+      side and bottom of every raw `.sheet` and swallowed a pushed picker's selection.
+      The tell that this rule was skipped: one module's sheets look different from the rest of
+      the app after an OS upgrade, and the fix already exists in the shared layer.
+      Exception: an affordance the OS itself owns end to end — a share sheet, an Add-to-Siri
+      sheet, a photo picker — stays on the system API. Wrapping those changes nothing and
+      breaks their behaviour.
+
+  - id: PLAT-02
+    title: A self-sizing presentation only works if the content reports its size
+    severity: important
+    enforcement: judgement
+    rationale: readability
+    check: >
+      A content-sized detent asks the content how tall it is. A plain geometry read inside the
+      presentation answers with the frame the presentation already gave it — so the sheet
+      latches onto its own current height and never grows. Either publish the height the way
+      the framework expects (per region, the way the shared scaffold does) or use a fixed
+      height. Do not mix: a content detent with no reporter is a sheet that opens at the wrong
+      size in one locale and looks right in another.
+      The mirror-image mistake is worse, because it looks like a fix: pre-sizing the content so
+      it "reports a better height". A `fixedSize(vertical:)` at the presentation root measures
+      the content against an unconstrained WIDTH proposal — every line of copy lays out on one
+      line, and the height that comes back is a fraction of the real one. The sheet then opens
+      at two lines tall with the text clipped. When the presentation already measures its
+      content (an intrinsic-size host, a per-region scaffold), the content must add NOTHING:
+      no `fixedSize`, no geometry read, no frame. Check which key the engine actually observes
+      before publishing one — publishing to a key nothing reads is dead code that reads as a fix.
+      A content-sized presentation is also only as good as WHEN it measures. If the panel reads
+      the content's intrinsic size during the present animation — before the hosting view has its
+      final width — copy that wraps reports a fraction of its real height and the sheet opens
+      short. It cannot recover on its own when the follow-up measurement reads the RENDERED
+      height, because the short panel is already clamping that: the wrong size is a fixed point
+      until the user drags the sheet, which is exactly what the bug report will describe. The fix
+      belongs in the presentation engine — one re-read after the transition settles — not in each
+      caller. The tell that it is a measurement-timing bug and not a detent choice: a wheel picker
+      in the same engine is fine, because its ideal height does not depend on width.
+      A fixed detent is not the workaround either. `[.medium, .large]` on short content leaves
+      dead space, and on tall content clips the primary button. If the content has a natural
+      height, say so with a content detent and one shared cap.
+      When a presentation moves to a different engine, DELETE the previous engine's modifiers
+      from the content. `presentationDetents` / `presentationDragIndicator` /
+      `presentationBackground` left on a view that a UIKit-hosted panel now presents are silent
+      no-ops, and the next reader will believe the sheet is sized there and debug the wrong file.
+      A content-sized panel asks its content one question: how tall do you want to be? The
+      content must be able to answer it. Two answers that are not answers, and each produces the
+      opposite symptom:
+      - **A trailing `Spacer`** answers "all of it". The panel opens at its cap with the real
+        content stranded at the top. A content-sized sheet's root stack has no `Spacer` — its own
+        height IS the answer; use padding for the bottom clearance.
+      - **Copy with no width** answers "one line per paragraph". Height that is entirely a
+        function of where lines break cannot be measured without a width, so the sheet opens
+        short and clips. Hand the presenting screen's measured width down to the content.
+      Diagnose by comparing against a sheet in the same engine that works. If one is fine and
+      another is not, the engine is not the bug — and a shared-engine change to fix one screen
+      puts every other domain's sheets at risk for a fix nobody has verified. Fix it where the
+      content is.
+      When a presentation moves to a different engine, DELETE the previous engine's modifiers
+      from the content. `presentationDetents` / `presentationDragIndicator` /
+      `presentationBackground` left on a view that a UIKit-hosted panel now presents are silent
+      no-ops, and the next reader will believe the sheet is sized there and debug the wrong file.
+      A fixed detent is not the workaround either: `[.medium, .large]` on short content leaves
+      dead space, and on tall content clips the primary button.
+      Verify presentation sizing on a device or simulator before calling it done. This is not a
+      thing a diff shows, and it is not a thing to guess at twice.
+
+  - id: PLAT-03
+    title: Assets come from the app's own CDN
+    severity: blocking
+    enforcement: lint
+    mechanism: 'custom regex: https?:// host not on the app''s own domains, in a non-test source'
+    rationale: security
+    check: >
+      An image or asset URL pointing at a third-party host is a finding even when it renders
+      correctly: the host is outside our control and versioning, it can change or disappear
+      under us, and every render leaks a request to a party the user never agreed to. The
+      carrier logo, the flag, the banner — they all exist on the app's own CDN. Put the URL in
+      the module's constants namespace so there is one place to change it.
+
+  # ── SAFE ──────────────────────────────────────────────────────────────────
+  - id: SAFE-01
+    title: Escaping closures capture self weakly and unwrap immediately
+    severity: important
+    enforcement: lint
+    mechanism: 'custom regex: escaping closure body referencing self without a weak capture list'
+    rationale: security
+
+  - id: SAFE-02
+    title: A calendar day sent to a service uses the shared calendar-day helper
+    severity: blocking
+    enforcement: lint
+    mechanism: 'custom regex: DateFormatter constructed in a mapper or repository path'
+    rationale: security
+
+  # ── VIS — declaration & visibility ────────────────────────────────────────
+  - id: VIS-01
+    title: Every class is final unless a real subclass exists in the module
+    severity: important
+    enforcement: lint
+    mechanism: 'custom regex: ^\s*(public |internal )?class\b not preceded by final'
+    rationale: readability
+
+  - id: VIS-02
+    title: Explicit access level, private by default; internal handled consistently
+    severity: important
+    enforcement: lint
+    mechanism: swiftlint private_outlet, explicit_acl (opt-in) — scoped to the module's convention
+    rationale: readability
+
+  - id: VIS-03
+    title: Mutability and conformance declared as narrowly as the type allows
+    severity: suggestion
+    enforcement: lint
+    mechanism: swiftlint prefer_let, prefer_self_in_static_references
+    rationale: testability
+
+  - id: VIS-04
+    title: The surviving public surface and every seam contract carries a doc comment
+    severity: important
+    enforcement: lint
+    mechanism: swiftlint missing_docs scoped to public declarations
+    rationale: flexibility
+    check: The one place the no-unnecessary-comments rule inverts — a cross-module contract cannot explain itself through naming.
+
+  # ── UI ────────────────────────────────────────────────────────────────────
+  - id: UI-01
+    title: A screen's composite view is never consumed by another screen
+    severity: blocking
+    enforcement: judgement
+    rationale: flexibility
+
+  - id: UI-02
+    title: No new component is added to a UI target the module marks as frozen
+    severity: important
+    enforcement: lint
+    mechanism: CI check on new files under the frozen target path
+    rationale: flexibility
+
+  - id: UI-03
+    title: Every screen with user actions has its analytics surface; no direct generated-event calls
+    severity: important
+    enforcement: judgement
+    rationale: readability
+
+  - id: UI-04
+    title: All user copy goes through the screen's copy surface
+    severity: important
+    enforcement: lint
+    mechanism: 'custom regex: raw localization key access inside Scene/ViewModel'
+    rationale: flexibility
+
+  # ── MOD — modularity ──────────────────────────────────────────────────────
+  - id: MOD-01
+    title: A feature module never imports another feature module
+    severity: blocking
+    enforcement: lint
+    mechanism: 'custom regex per module: ^import (<sibling feature names>)'
+    rationale: flexibility
+    check: A feature that imports many siblings to compose them has promoted itself to a second composition root — highest severity in this section.
+
+  - id: MOD-02
+    title: The manifest graph is one-way and acyclic; core never depends on a feature
+    severity: blocking
+    enforcement: scan
+    rationale: flexibility
+    check: Check as policy, not by trusting the build — a package-level cycle can still build. Report dead edges (declared, never imported).
+
+  - id: MOD-03
+    title: Shared values walk the placement ladder, cheapest rung first, with a stated reason to climb
+    severity: important
+    enforcement: judgement
+    rationale: flexibility
+
+  - id: MOD-04
+    title: Removability delta — removing the module touches only the composition root
+    severity: blocking
+    enforcement: scan
+    rationale: flexibility
+    metric: "files touched to remove the module (target: composition root only)"
+
+  - id: MOD-05
+    title: DI is by abstraction; each module wires only itself
+    severity: blocking
+    enforcement: judgement
+    rationale: testability
+    check: >
+      Resolving a concrete type owned by another feature module is a compile-time dependency in a
+      runtime disguise. The composition root is the only place that knows the module list.
+
+  - id: MOD-06
+    title: The public surface is the plug — entry types only, everything else internal
+    severity: important
+    enforcement: scan
+    rationale: flexibility
+    metric: "public declarations divided by externally consumed symbols (target ~1)"
+
+  - id: MOD-07
+    title: No shared mutable state across the boundary; the module owns its own assets and copy
+    severity: blocking
+    enforcement: judgement
+    rationale: flexibility
+
+  # ── CONC — concurrency ────────────────────────────────────────────────────
+  - id: CONC-01
+    title: The isolation policy is one declared decision applied everywhere
+    severity: important
+    enforcement: judgement
+    rationale: readability
+    applies_when: module is in Swift 6 language mode (otherwise suggestion)
+    check: A reader must know where a function runs from its declaration, without tracing callers.
+
+  - id: CONC-02
+    title: Sendable conformance is stated where it is load-bearing, consistently
+    severity: suggestion
+    enforcement: judgement
+    rationale: readability
+
+  - id: CONC-03
+    title: Escape hatches are justified and counted
+    severity: important
+    enforcement: lint
+    mechanism: 'custom regex: @preconcurrency|nonisolated\(unsafe\)|@unchecked Sendable'
+    rationale: security
+    metric: "escape-hatch count by kind (target: flat or falling)"
+    check: A growing count silently returns the module to pre-Swift-6 guarantees while the build stays green.
+
+  - id: CONC-04
+    title: One concurrency model — no GCD, semaphore or completion handler layered onto async
+    severity: important
+    enforcement: lint
+    mechanism: 'custom regex: DispatchQueue|DispatchSemaphore|DispatchGroup in async-adopted paths'
+    rationale: readability
+
+  - id: CONC-05
+    title: Every task has an owner and a cancellation story
+    severity: important
+    enforcement: judgement
+    rationale: testability
+
+  # ── TEST — testability by design ──────────────────────────────────────────
+  - id: TEST-01
+    title: The environment is injected, never reached for
+    severity: blocking
+    enforcement: lint
+    mechanism: 'custom regex scoped to logic paths: Date\(\)|UUID\(\)|UserDefaults|\.random|Locale\.current'
+    rationale: testability
+    check: >
+      Time, calendar, randomness, UUID, locale, storage, network, feature flags and session state
+      arrive through an abstraction. A logic type calling these directly is untestable by
+      construction — no amount of test-writing discipline fixes it.
+
+  - id: TEST-02
+    title: Business rules are callable without a view, navigation or network
+    severity: important
+    enforcement: judgement
+    rationale: testability
+    check: Decision logic returns a value rather than mutating far-away state.
+
+  - id: TEST-03
+    title: No static or singleton access from the logic layer
+    severity: important
+    enforcement: lint
+    mechanism: 'custom regex: \.shared\b|\.main\.container outside composition/DI paths'
+    rationale: testability
+
+  - id: TEST-04
+    title: Test doubles follow one named taxonomy — stub, spy, fake, mock
+    severity: suggestion
+    enforcement: judgement
+    rationale: testability
+    check: One kind per file, name states the kind, signature parity with the real type (SVC-02).
+
+  - id: TEST-05
+    title: Async behaviour is testable — no unstructured task in logic, no sleep, injected clock
+    severity: important
+    enforcement: lint
+    mechanism: 'custom regex: Task\s*\{ in logic paths; sleep\( in test paths'
+    rationale: testability
+
+  - id: TEST-06
+    title: Tests mirror the source tree across the module's declared layers
+    severity: important
+    enforcement: scan
+    rationale: testability
+    metric: "screens with production logic and no mirrored test folder (target 0)"
+
+  - id: TEST-07
+    title: The module's test target compiles with no sibling feature present
+    severity: blocking
+    enforcement: scan
+    rationale: testability
+
+  # ── FLEX — intra-module flexibility ───────────────────────────────────────
+  - id: FLEX-01
+    title: Layers meet through protocols; no concrete cross-layer type in a signature
+    severity: important
+    enforcement: judgement
+    rationale: testability
+
+  - id: FLEX-02
+    title: Variants are configuration, not branching
+    severity: important
+    enforcement: judgement
+    rationale: flexibility
+    check: A conditional whose branches differ only in tokens or copy is a finding.
+
+  - id: FLEX-03
+    title: Components are open for extension — a new variant does not edit the existing body
+    severity: important
+    enforcement: judgement
+    rationale: flexibility
+
+  - id: FLEX-04
+    title: Feature flags are resolved at the boundary and carry a removal condition
+    severity: important
+    enforcement: lint
+    mechanism: 'custom regex: flag access inside a view body'
+    rationale: flexibility
+
+  - id: FLEX-05
+    title: No layer's vocabulary leaks into another — presentation types never travel downward
+    severity: important
+    enforcement: judgement
+    rationale: flexibility
+
+  # ── SEC — security & privacy ──────────────────────────────────────────────
+  - id: SEC-01
+    title: Sensitive data persists only when it must, and then only in the Keychain
+    severity: blocking
+    enforcement: lint
+    mechanism: >
+      custom regex generated from the module's sensitive-data inventory, in two directions:
+      (a) a resolved sensitive symbol written to UserDefaults, a plist, a file or the local
+      database; (b) a symbol the inventory marks transient appearing in ANY persistence call,
+      keychain included
+    rationale: security
+    applies_to_classes: all
+    check: >
+      Walk persistence_decision first. Most sensitive values in a flow are used and dropped —
+      those stay in memory, and writing them to the Keychain is itself a finding, because an
+      unnecessary keychain item outlives the flow, survives logout unless someone deletes it, and
+      creates a cleanup obligation with no owner. Only a value that must survive app restart is
+      persisted, and then: Keychain only, with an explicit accessibility class matching the data
+      (device-only unless a documented reason exists), no iCloud sync, biometric or passcode
+      gating where policy requires. never-persist-locally classes stay transient regardless.
+      Report both over-persistence and under-protection — they are equally findings.
+
+  - id: SEC-02
+    title: No hardcoded secrets — anything in source is treated as already leaked
+    severity: blocking
+    enforcement: lint
+    mechanism: 'custom regex: (api[_-]?key|secret|password|bearer|private[_-]?key)\s*[:=]\s*"'
+    rationale: security
+
+  - id: SEC-03
+    title: Logging never carries sensitive data; log interpolation defaults to private
+    severity: blocking
+    enforcement: lint
+    mechanism: >
+      custom regex generated from the module's sensitive-data inventory: any resolved symbol
+      interpolated into a log call, plus a blanket ban on print( and on logging a raw
+      request/response body
+    rationale: security
+    applies_to_classes: all
+    check: >
+      Every class marked loggable:never is redacted; membership-identity is hashed or truncated
+      where it must appear at all. Interpolated values are private by default and only values
+      explicitly known to be non-sensitive are made public — the default must fail safe, because
+      the cost of a missed annotation is a logged credential.
+
+  - id: SEC-04
+    title: Transport is HTTPS and ATS-compliant; an exception needs a written reason and an expiry
+    severity: blocking
+    enforcement: lint
+    mechanism: Info.plist ATS key scan + custom regex for http:// literals
+    rationale: security
+
+  - id: SEC-05
+    title: Sensitive data has a lifetime
+    severity: important
+    enforcement: judgement
+    rationale: security
+    check: >
+      Cleared on logout and session end; sensitive screens hidden from the app-switcher snapshot;
+      pasteboard writes explicit and expiring; nothing sensitive cached to disk by default.
+
+  - id: SEC-06
+    title: Analytics and crash payloads are redacted
+    severity: blocking
+    enforcement: judgement
+    rationale: security
+    check: Cross-check every analytics event's parameter list, user properties, breadcrumbs and non-fatal payloads for PII.
+
+  - id: SEC-07
+    title: Permissions are least-privilege with accurate purpose strings
+    severity: important
+    enforcement: scan
+    rationale: security
+    check: A permission requested but unused is a finding — a privacy problem and an App Review risk.
+
+  - id: SEC-08
+    title: The privacy manifest is complete and honest
+    severity: blocking
+    enforcement: scan
+    rationale: security
+    check: Declared data types match what the module actually collects; required-reason APIs carry a valid reason code.
+
+  - id: SEC-09
+    title: Debug and mock affordances are excluded from the store build by a real mechanism
+    severity: blocking
+    enforcement: lint
+    mechanism: >
+      custom regex for the commented-out compilation directive only (a "// #if" is not a guard —
+      the code inside it ships). Whether an affordance is actually gated is JUDGEMENT: once the
+      gate is a resolved capability rather than a compile-time condition, no regex can see it —
+      a pattern that looked for "#if DEBUG nearby" flags the gated call site and the debug type's
+      own declaration alike, which is noise, not signal.
+    rationale: security
+    check: >
+      The rule is store-build exclusion, not "#if DEBUG" specifically. Internal, TestFlight and
+      enterprise distributions may legitimately carry a debug menu; the store build must not. The
+      question to answer per affordance is "what removes this from the store build?", and any
+      mechanism that actually fires there is acceptable.
+
+      Three failure shapes, all findings:
+      1. No gate — the affordance is unconditionally compiled and reachable.
+      2. A commented-out gate — "// #if DEBUG" reads like protection and provides none. Usually a
+         symptom of shape 3 rather than carelessness.
+      3. A gate that fires in the wrong builds — "#if DEBUG" in a Release-configured internal
+         build strips the affordance from exactly the testers who need it, so someone eventually
+         comments it out and it reaches the store. Diagnose this as a missing mechanism, never as
+         "restore the directive": restoring it re-breaks the internal build.
+
+      Know the constraint before proposing a fix. A SwiftPM module does not inherit the app
+      target's SWIFT_ACTIVE_COMPILATION_CONDITIONS, and SwiftPM's .when(configuration:) predicate
+      distinguishes only debug from release — a custom Xcode configuration is invisible inside the
+      package. Where a module needs a three-way distinction (local / internal / store), a
+      compile-time condition alone cannot express it.
+
+      Prefer, in order: (a) the composition root resolves the distribution channel once and
+      injects it as a capability the module consumes through an abstraction, so the module never
+      knows how it was distributed — this also satisfies MOD-05; (b) a build-injected Info.plist
+      flag read at startup; (c) a runtime channel probe such as the absence of an embedded
+      provisioning profile. Whichever is chosen it must be ONE shared mechanism: one per module
+      means nobody can answer "is this in the store build?" without reading every call site.
+
+  # ── DEPR — deprecation debt ───────────────────────────────────────────────
+  - id: DEPR-01
+    title: No call site of a deprecated API — platform or in-repo
+    severity: important
+    enforcement: scan
+    rationale: flexibility
+    metric: "deprecated call sites (target 0, and never rising)"
+    check: >
+      Two sources, both count. Platform deprecations surface only in a build log, so harvest them
+      from the build the module is actually verified with (WARN-01) rather than guessing. In-repo
+      deprecations are greppable: find every `@available(*, deprecated)` declaration across the
+      repo, then count this module's call sites of each.
+      A deprecation nobody migrates is worse than no deprecation — it trains readers to ignore the
+      warning, and it hides the one that matters. Report per deprecated symbol: declaration site ·
+      replacement named in the message · this module's call-site count · migration owner.
+
+  - id: DEPR-02
+    title: Our own deprecations name a replacement and have a removal condition
+    severity: important
+    enforcement: lint
+    mechanism: 'custom regex: @available(*, deprecated) without a message:, and a deprecated declaration still referenced in-module'
+    rationale: flexibility
+    check: >
+      A deprecation without a stated replacement is a complaint, not a migration. Every
+      `@available(*, deprecated, message:)` says what to use instead and, in the plan, who owns
+      the removal and when. A deprecated symbol with zero remaining call sites is deleted, not
+      left as furniture.
+
+  - id: DEPR-03
+    title: Governance docs never prescribe a deprecated API
+    severity: blocking
+    enforcement: judgement
+    rationale: readability
+    check: >
+      Cross-check the module's own docs against the deprecation list. When a doc mandates a
+      pattern whose API is deprecated, every new screen built to the doc adds fresh debt, and the
+      developer following the standard is punished for it. This outranks the individual call
+      sites: fix the doc first, then migrate, or the count grows faster than the migration.
+
+  - id: DEPR-04
+    title: Availability gates below the deployment target are removed
+    severity: suggestion
+    enforcement: lint
+    mechanism: 'custom regex: @available / #available naming a version at or below the package deployment target'
+    rationale: readability
+    check: >
+      An `if #available(iOS 16)` in a module that already requires iOS 17 is dead branching a
+      reader must still evaluate. Forward gates (above the target) are legitimate and stay.
+
+  # ── WARN — warning debt ───────────────────────────────────────────────────
+  - id: WARN-01
+    title: The module's build produces zero warnings, and the count never rises
+    severity: important
+    enforcement: scan
+    rationale: readability
+    metric: "compiler warnings for this module (target 0, hard requirement: not increasing)"
+    check: >
+      Harvest from the module's real verification build (an xcresult or a build log — the one the
+      team actually runs, since some targets cannot be built from the CLI). Group by warning kind
+      and report the top kinds, not just a total: one repeated warning across 40 files is a single
+      fix, and a total hides that.
+      Warnings are the canary for deprecation, concurrency and unused-code debt at once. A build
+      with 300 warnings has no working warning channel — the next real one is invisible, which is
+      the actual cost. Treat the count as a ratchet even when zero is out of reach today.
+
+  - id: WARN-02
+    title: A TODO carries an owner or a ticket, and no FIXME survives a release
+    severity: suggestion
+    enforcement: lint
+    mechanism: 'custom regex: TODO or FIXME without a bracketed tag or ticket reference'
+    rationale: readability
+    metric: "untagged TODO count (target 0), FIXME count (target 0)"
+    check: >
+      `// TODO[SWAGGER-208458421]: …` is a tracked decision; a bare `// TODO:` is a note to a
+      person who has left. Tagging is cheap and makes the debt countable. FIXME means "known
+      broken" and belongs in the tracker, not the source.
+
+  # ── A11Y ──────────────────────────────────────────────────────────────────
+  - id: A11Y-01
+    title: An identifier from the shared source on every interactive element
+    severity: important
+    enforcement: lint
+    mechanism: custom regex for interactive modifiers without an accessibility identifier
+    rationale: testability
+
+  - id: A11Y-02
+    title: Localized VoiceOver label, plus a hint where the action is not obvious
+    severity: important
+    enforcement: judgement
+    rationale: accessibility
+
+  - id: A11Y-03
+    title: Minimum 44x44 tap target; grouped content exposes one meaningful element
+    severity: important
+    enforcement: judgement
+    rationale: accessibility
+
+  - id: A11Y-04
+    title: Dynamic Type does not break layout at the largest accessibility sizes
+    severity: important
+    enforcement: judgement
+    rationale: accessibility
+    check: No fixed-height container holding scalable text.
+
+  - id: A11Y-05
+    title: RTL mirrors correctly; no leading/trailing hardcoded as left/right
+    severity: important
+    enforcement: lint
+    mechanism: 'custom regex: \.left|\.right in alignment and padding edges'
+    rationale: accessibility
+
+  # ── PERF — minimal set; the boundary is declared in STANDARD.md ───────────
+  - id: PERF-01
+    title: No expensive computation inside a view body
+    severity: important
+    enforcement: judgement
+    rationale: performance
+
+  - id: PERF-02
+    title: Lists and grids use lazy containers with stable identity
+    severity: important
+    enforcement: lint
+    mechanism: 'custom regex: ForEach over indices as identity; VStack over a large collection'
+    rationale: performance
+
+  - id: PERF-03
+    title: No blocking work at init or on the main actor — decoding, file I/O, JSON
+    severity: important
+    enforcement: judgement
+    rationale: performance
+
+  - id: PERF-04
+    title: No per-render construction of formatters, calendars or regexes
+    severity: suggestion
+    enforcement: lint
+    mechanism: 'custom regex: DateFormatter(|NumberFormatter(|Regex( inside a view body'
+    rationale: performance