diff --git a/.github/workflows/ci-pr.yml b/.github/workflows/ci-pr.yml
index 812d031..585d0f8 100644
--- a/.github/workflows/ci-pr.yml
+++ b/.github/workflows/ci-pr.yml
@@ -17,6 +17,10 @@ jobs:
- name: Checkout Repository
uses: actions/checkout@v7
+ - name: Validate latest Codex review policy
+ uses: thatfactory/agent-guidelines/.github/actions/codex-review-policy@1c957669005eea010131c53f0a4146db2ccf7859
+ with:
+ profile: full
- name: Validate Consumer Integration
run: AgentGuidelines/Scripts/validate_consumer_setup.swift
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index cea53a9..7fc8f82 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -18,6 +18,10 @@ jobs:
- name: Checkout Repository
uses: actions/checkout@v7
+ - name: Validate latest Codex review policy
+ uses: thatfactory/agent-guidelines/.github/actions/codex-review-policy@1c957669005eea010131c53f0a4146db2ccf7859
+ with:
+ profile: full
- name: Validate Consumer Integration
run: AgentGuidelines/Scripts/validate_consumer_setup.swift
diff --git a/AGENTS.md b/AGENTS.md
index 268ceac..8e9d753 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -27,21 +27,28 @@ Read only the guides relevant to the task:
Redux, SwiftUI, and application-localization guidance do not apply to the package target.
-
+
+
## Code Review Rules
-Review for release-blocking defects introduced or materially exposed by the pull request. A clean review means no unresolved P0/P1 findings; it does not mean exhaustive or perfect software.
+Report only substantiated P0/P1 defects introduced or materially exposed by this change. Require a concrete, reachable failure in a supported use case or documented threat model, with serious impact such as a security-boundary bypass, durable data loss or corruption, a crash or deadlock in an important workflow, loss of availability, or a serious compatibility regression. An acceptance-criterion violation alone does not establish P1 severity.
-A blocking finding must identify a concrete, reachable path in a supported use case or the documented threat model that can cause a credible security-boundary bypass, durable data loss or corruption, a crash or deadlock, loss of availability, violation of an explicit acceptance criterion, or a serious compatibility regression.
+For each finding, state severity, preconditions, execution path, impact, evidence, and actionable remediation. Group manifestations of one root cause. Report substantiated blockers together. Omit unsolicited P2/P3 observations, style preferences, speculative hardening, optional tests, and refactors. A clean review means no unresolved P0/P1 blockers, not perfect software.
-For every blocking finding, state the severity, preconditions, execution path, impact, evidence, and actionable remediation. Group manifestations that share the same root cause into one finding.
+A follow-up review covers unresolved P0/P1 findings, changes since the previous reviewed commit, and directly affected code. Do not restart a full review of unchanged code. New follow-up findings must be P0/P1 defects introduced by remediation or genuinely hidden by the previous blocker.
+
-Treat P2/P3 observations as non-blocking, including defense-in-depth, theoretical completeness, unsupported use cases, malformed state that trusted code cannot produce, behavior by components outside the threat model, style preferences, and speculative refactoring. Record a useful lower-severity observation once as deferred, declined, duplicate, or follow-up work; do not keep the review loop open for it.
+
+## Pull Request Lifecycle
-In an initial review, report substantiated blockers together. A follow-up review is limited to unresolved P0/P1 findings, changes since the last reviewed commit, and code directly affected by those changes. Do not restart an unrestricted review of unchanged code. A new follow-up finding must be a P0/P1 defect introduced by the remediation or genuinely hidden by the previous blocker.
+Finish implementation, inspect the diff, and run relevant local validation before opening a ready-for-review PR. Drafts are for incomplete preparation; mark ready before waiting for automatic review. Keep the review head stable while the initial review runs. One automatic Codex review is the initial review; never duplicate it with a manual request or repeatedly toggle draft/ready state.
-Automatic Codex review is the initial review. Do not request a manual Codex review unless the repository owner explicitly asks. Never request another review after each remediation commit. Within the normal review budget, at most one owner-authorized, delta-scoped verification review may be requested under [the pull-request review workflow](AgentGuidelines/Guidelines/GitHub/PullRequests.md).
-
+Establish review configuration from repository-specific evidence. Verify the bot, PR, review round, and reviewed commit using PR/request-comment reactions, review submissions, inline threads, and checks. Eyes means processing, not approval; a thumbs-up means no suggestions only for its verified review round. Historical reactions, missing comments, and elapsed time never certify a newer head. Monitor at most five minutes total with bounded, non-accelerating polls; timeout leaves a required gate unresolved and never authorizes merge.
+
+Batch accepted P0/P1 fixes, verify them locally, rerun affected checks, and disposition and resolve every review thread. A completed initial review plus an explicitly recorded, locally verified remediation-only delta can satisfy the review gate; do not claim Codex reviewed the newer head. New unrelated scope belongs in another PR. Request at most one delta-scoped verification only when the owner explicitly authorizes it. Do not request reviews after every fix or casually mention the bot to start extra work. Separate Security Review is manual and requires explicit owner instruction.
+
+Before merge, rerun the latest published review-policy check, confirm no required review is pending, no unresolved P0/P1 blocker remains, every thread is dispositioned and resolved, required checks pass on the current head, and existing human approval or merge authorization is satisfied. A bot thumbs-up is not a substitute for required GitHub approval. Opening a PR does not authorize merging it.
+
## Physical folder map
@@ -76,19 +83,21 @@ Treat privacy-safe runtime observability as part of implementing or changing sta
Every ThatFactory package log starts with its canonical emoji and uses its own stable subsystem. Never log credentials, account or record identifiers, share URLs, captured content, images, or other user-generated values as public metadata. Keep pure values and utilities silent when they have no meaningful diagnostic event; record that deliberate decision in the implementation handoff instead of adding initializer or property-access noise. Follow [Logging](AgentGuidelines/Guidelines/Logging.md) for ownership, privacy, severity, message design, and tests.
-
+
## External Dependency Policy
Do not introduce third-party source or binary dependencies into ThatFactory applications, games, or reusable packages during normal development. Prefer Apple platform APIs, the Swift standard library, code owned by the current repository, or focused ThatFactory-owned packages. If reusable capability is missing, implement it natively at the appropriate boundary and consider extracting it into a first-party package instead of selecting an external library.
-A third-party dependency may be added, or expanded to a new target or runtime role, only with explicit repository-owner approval for that specific use before modifying the dependency graph. Convenience, reduced implementation effort, popularity, or an agent's preference for an existing library are not sufficient justification. Do not make an external library acceptable merely by hiding it behind a first-party wrapper.
+A third-party dependency may be added, or expanded to a new target or runtime role, only under an explicit standing approval in these guidelines or with explicit repository-owner approval for that specific use before modifying the dependency graph. Convenience, reduced implementation effort, popularity, or an agent's preference for an existing library are not sufficient justification. Do not make an external library acceptable merely by hiding it behind a first-party wrapper.
Document every approved exception in durable repository documentation in the same change. Record the dependency and source, purpose and target scope, why a native or first-party implementation is not appropriate, relevant license, security, and maintenance considerations, and the approval context. Merely mentioning or using the dependency in an execution plan, pull-request description, or transient chat is not approval. Regardless of where explicit approval occurs, reflect the exception in durable repository documentation.
Apple system frameworks and the Swift standard library are not third-party dependencies. ThatFactory-owned packages are first-party dependencies. Tooling explicitly required by the shared guidelines is allowed only for its documented tooling role and must not be linked into or shipped with product runtime targets unless separately approved and documented.
+Follow [Networking](AgentGuidelines/Guidelines/Networking.md) for Apple-native networking and typed HTTP. Its narrow standing approval for Apple's `swift-http-types` applies only to the documented HTTPTypes and HTTPTypesFoundation runtime role; it does not approve other Apple open-source packages or unrelated roles. Use the guide's normal dependency documentation for that role instead of requesting a separate consumer exception.
+
Follow [Development workflow](AgentGuidelines/Guidelines/Development.md) for the detailed policy.
-
+
## Documentation Maintenance
@@ -100,20 +109,8 @@ Update documentation when a change alters durable or core feature behavior or an
Do not create documentation churn for incidental implementation details that are not durable and do not affect an existing documented claim. Follow [Documentation](AgentGuidelines/Guidelines/Documentation.md) for detailed scope and the completion checklist.
-
-## Code Review Rules
-
-Review for release-blocking defects introduced or materially exposed by the pull request. A clean review means no unresolved P0/P1 findings; it does not mean exhaustive or perfect software.
-
-A blocking finding must identify a concrete, reachable path in a supported use case or the documented threat model that can cause a credible security-boundary bypass, durable data loss or corruption, a crash or deadlock, loss of availability, violation of an explicit acceptance criterion, or a serious compatibility regression.
-
-For every blocking finding, state the severity, preconditions, execution path, impact, evidence, and actionable remediation. Group manifestations that share the same root cause into one finding.
-
-Treat P2/P3 observations as non-blocking, including defense-in-depth, theoretical completeness, unsupported use cases, malformed state that trusted code cannot produce, behavior by components outside the threat model, style preferences, and speculative refactoring. Record a useful lower-severity observation once as deferred, declined, duplicate, or follow-up work; do not keep the review loop open for it.
-In an initial review, report substantiated blockers together. A follow-up review is limited to unresolved P0/P1 findings, changes since the last reviewed commit, and code directly affected by those changes. Do not restart an unrestricted review of unchanged code. A new follow-up finding must be a P0/P1 defect introduced by the remediation or genuinely hidden by the previous blocker.
-The review-round budget below applies only to Codex GitHub reviews: the configured automatic Codex review and any manual `@codex review` request. It does not apply to ChatGPT review or reasoning delegated through Reasoning Relay. An otherwise-authorized Reasoning Relay workflow may request as many Relay review or follow-up delegations as its own governing workflow requires; those requests neither consume the Codex budget nor require repository-owner authorization under it.
+## Codex review configuration
-Automatic Codex review is the initial Codex review. Do not request a manual Codex review unless the repository owner explicitly asks. Never request another Codex review after each remediation commit. Within the normal Codex review budget, at most one owner-authorized, delta-scoped Codex verification review may be requested under [the pull-request review workflow](AgentGuidelines/Guidelines/GitHub/PullRequests.md).
-
+Automatic Codex PR review is enabled. Use all PR authors and the opening/ready trigger, keep exhaustive review off, and keep separate Security Review manual. Apply the managed lifecycle; do not request a duplicate manual review. The policy-validation hosting check is required for merge.
diff --git a/AgentGuidelines/.agents/skills/agent-guidelines-audit/SKILL.md b/AgentGuidelines/.agents/skills/agent-guidelines-audit/SKILL.md
index 75510ae..f0ecbce 100644
--- a/AgentGuidelines/.agents/skills/agent-guidelines-audit/SKILL.md
+++ b/AgentGuidelines/.agents/skills/agent-guidelines-audit/SKILL.md
@@ -27,17 +27,147 @@ Review the actual change rather than only checking whether files exist:
- Confirm physical folders, familiar domain grouping, filenames, declaration order, type ownership, namespacing, documentation, and `MARK` organization follow the applicable guides. Distinguish values that describe data from tools that primarily execute algorithms or accumulate behavior.
- For Redux applications, trace actions, state, reducers, middleware, services, tools, presentation models, views, and side-effect results through the complete data flow. Confirm each Redux component folder contains only that component type.
- Check that framework objects, persistence, logging, and asynchronous work remain in their allowed boundaries.
+- Perform the mandatory [networking check](#audit-networking) for network implementation, dependency changes, and networking-policy adoption.
- Check SwiftUI composition, narrow inputs, local versus durable state, localization, accessibility, and safe deterministic previews where applicable.
+- For each new or changed SwiftUI `ScrollView`, apply the shared [scrolling guidance](../../../Guidelines/Swift/SwiftUI.md#scrolling): verify `.scrollBounceBehavior(.basedOnSize)` covers its scrolling axes on supported deployment targets, including scroll views in modal sheets. Check the modifier's environment scope around nested scrollables and require a documented interaction reason for a different bounce behavior.
+- Perform the mandatory [native-component and presentation decision check](#audit-native-components-and-presentation) for changed SwiftUI controls and presentation behavior.
+- Perform the mandatory [system-control placement check](#audit-system-control-placement) for changed navigation, toolbars, dismissal controls, and window chrome, including affected UIKit/AppKit wrappers.
+- Perform the mandatory [animation and image-rendering check](#audit-animation-and-image-rendering) for changed visual transitions, reusable control styles, and dynamic image paths, including directly affected consumers.
+- Perform the [Reduce Motion check](#audit-reduce-motion) for affected motion and for Reduced Motion support declarations.
+- Perform the [tvOS current-user identity check](#audit-tvos-current-user-identity) when changed behavior relies on selected-profile preferences, CloudKit accounts, or personal store binding.
- Check tests for the required framework, mirrored paths, shared tags, Given/When/Then structure, deterministic seams, and coverage of changed behavior and failure paths.
- Trace every new or changed stateful, asynchronous, fallible, or lifecycle-oriented behavior and verify that its owning artifact emits privacy-safe AppLogger events for the meaningful success, failure, cancellation, recovery, and state-transition outcomes needed to diagnose it. Dependency declaration and target linkage alone do not establish logging coverage. Accept silence for pure values or utilities only when there is no meaningful event boundary and the implementation handoff records that deliberate decision.
- Check logging ownership, subsystem, categories, emoji, privacy, severity, metadata stability, noise controls, and focused formatter or sink tests when logging changed.
+- For every in-scope package that emits logs, resolve its canonical emoji from local instructions or documentation and the package list on the current `main` branch of the [ThatFactory Swift Package Collection](https://github.com/thatfactory/swift-package-collection). Enumerate the registered package entries and require each canonical emoji to identify exactly one package, treating visually identical presentation-selector variants as a collision. Confirm the package documentation, package-local logging gateway, and registry entry use the same emoji. When creating a package or assigning or changing its emoji, verify the intended emoji is unused before accepting it and require the registry update in the publication work. A collision, a missing registry entry for a published package, an unreachable current registry, or disagreement among these sources blocks audit completion and release readiness.
- For every Apple-platform application or Swift package in scope, except the AppLogger provider repository itself, verify integration with the shared [Logging guide](../../../Guidelines/Logging.md): confirm the AppLogger dependency is declared, the `AppLogger` library product is linked to every target that emits diagnostics, and any new project has it available in its primary runtime target before its first log call. Search the actual package or Xcode dependency graph rather than relying on an `import` alone, and treat `print`, direct `Logger` instances, or duplicate logging backends as incomplete integration when they emit project diagnostics. When implementation is authorized, add or repair the dependency and target linkage and migrate affected calls while preserving the guide's ownership, subsystem, category, emoji, privacy, severity, and noise rules; report an exact blocker when target or platform constraints make safe integration ambiguous.
-- Inspect dependency manifests, resolver or lock files, Xcode package references, vendored source or binary frameworks, and equivalent dependency declarations. Compare the change with the baseline and identify every new third-party dependency or expansion of an existing third-party dependency into a new target or runtime role. Apply the shared [external dependency policy](../../../Guidelines/Development.md#external-dependencies): require explicit repository-owner approval before the dependency is introduced and require the durable exception record in repository documentation. Do not infer approval merely from an execution plan, pull-request description, implementation convenience, package popularity, or the dependency already appearing in the diff. Treat an unapproved or undocumented third-party dependency as a blocker to completion. Do not flag Apple system frameworks, the Swift standard library, ThatFactory-owned packages, or guideline-mandated tooling used only for its documented tooling role. If a newly resolved transitive third-party package will be linked into or shipped with the product, verify that its owning direct dependency is covered by an approved exception rather than dismissing it solely because it is transitive.
+- Inspect dependency manifests, resolver or lock files, Xcode package references, vendored source or binary frameworks, and equivalent dependency declarations. Compare the change with the baseline and identify every new third-party dependency or expansion of an existing third-party dependency into a new target or runtime role. Apply the shared [external dependency policy](../../../Guidelines/Development.md#external-dependencies): verify any explicit standing approval covers the exact dependency and role; otherwise require explicit repository-owner approval before the dependency is introduced and require the durable exception record in repository documentation. Do not infer approval merely from an execution plan, pull-request description, implementation convenience, package popularity, or the dependency already appearing in the diff. Treat an unapproved or undocumented third-party dependency as a blocker to completion. Do not flag Apple system frameworks, the Swift standard library, ThatFactory-owned packages, or guideline-mandated tooling used only for its documented tooling role. Apply the [networking standing approval](../../../Guidelines/Networking.md#standing-dependency-approval) only within its documented scope. If a newly resolved transitive third-party package will be linked into or shipped with the product, verify that its owning direct dependency is covered by an approved role and the transitive package fits that role rather than dismissing it solely because it is transitive.
- Search dependency manifests, generated directories, project files, and documentation for CocoaPods or Carthage adoption. The shared [external dependency policy](../../../Guidelines/Development.md#external-dependencies) forbids both without an exception path and requires Swift Package Manager for package dependencies. When implementation is authorized, remove newly introduced adoption and its generated or configuration files; report pre-existing adoption as a completion blocker when safe migration is outside the task scope.
- Check package configuration, CI/CD, Xcode project configuration, security-sensitive changes, and physical-device limitations when they are in scope. For every Xcode project, perform the project-settings audit below. Compare documented Swift and concurrency settings with the effective application and test-target settings; flag both redundant isolation annotations and missing annotations at compiler-verified boundaries.
- Search for stale type names, superseded files, direct APIs forbidden by the new architecture, empty folders, and references to removed behavior.
- Apply the shared [CI/CD guide](../../../Guidelines/CICD.md) to workflow and repository-automation changes. Search scripts, generated directories, workflow files, and documentation for fastlane adoption and treat it as forbidden without an exception path. Require focused ThatFactory tooling or repository-owned Swift scripts for CI/CD and delivery, and inspect new repository-owned executable scripts for compliance. For Swift-focused applications, games, and packages, accept Python or POSIX shell only when durable repository documentation identifies the missing Swift capability, exact script and task scope, runtime and dependency requirements, security and maintenance impact, validation method, and revisit or removal condition. Reject convenience, familiarity, shorter code, an existing interpreter, or another non-Swift script as justification. Treat every exception as narrow; the central `Scripts/swift_format.sh` wrapper is the retained documented exception for invoking Xcode's `swift-format` modes.
-- For pull-request or merge readiness, apply the root `## Code Review Rules`: confirm the Codex review covers the current head, no allowed Codex review round is pending, every Codex review thread has a disposition, and no unresolved P0/P1 blocker remains. Treat P2/P3 observations as non-blocking and never request another Codex review unless the repository owner explicitly authorizes it. This Codex review-round budget does not apply to otherwise-authorized Reasoning Relay/ChatGPT review delegations; do not block them waiting for a Codex-budget exception.
+- For pull-request or merge readiness, apply the root review and lifecycle contracts and [review-policy integration](../../../ReviewPolicy/README.md). Rerun the latest published policy check immediately before merge. Require a completed initial Codex review for its recorded head, or that review plus a recorded locally verified remediation-only delta; do not claim the newer head was bot-reviewed. Confirm no allowed review is pending, every thread is dispositioned and resolved, and no unresolved P0/P1 blocker remains. Treat P2/P3 observations as non-blocking and never request another review unless the owner explicitly authorizes it. Review-only adoption enforces only these contracts, not unrelated engineering audits.
+
+## Audit runner toolchains
+
+Apply the [runner toolchain policy](../../../Guidelines/CICD.md#runner-toolchain) when reviewing or changing Apple build automation, adopting that policy, or performing an Xcode upgrade:
+
+1. Inspect every applicable workflow and its invoked scripts, setup actions, environment overrides, and runner labels. Search for Xcode/Swift version comparisons, build-number checks, allowlists, upper bounds, and versioned installation paths; inspecting workflow YAML alone is insufficient when a script performs the check.
+2. Verify ordinary CI uses and logs the runner's active toolchain. Distinguish version pins from minimum package tools versions, Swift language modes, SDK/deployment requirements, simulator destinations, and actual capability/readiness checks. A documented historical test version and a process-scoped selection for an explicit upgrade are not permanent CI constraints.
+3. For each retained pin, inspect the canonical guide's required repository exception and evidence. Do not invent a compatibility reason or treat the previous upgrade target as one. When implementation is authorized, remove unjustified pins and reconcile current setup documentation; in review-only work, report their locations and missing justification. An unjustified pin in scope prevents audit completion.
+4. Run affected toolchain reporting and the repository's build/test validation with the active installation. Record the selected Xcode/Swift versions, commands, outcomes, and any justified exception. Do not claim compatibility with untested future releases; removing a string check ensures those releases reach real validation.
+
+| Scenario | Audit outcome |
+| --- | --- |
+| New runner Xcode passes compilation and tests, but an old equality check fails | Remove the unjustified check and rerun affected validation |
+| Workflow accepts the runner, but its invoked script requires one build number | Treat the script as the same pin and require removal or a documented exception |
+| A supported package declares its minimum Swift tools version and language mode | Preserve the capability requirements |
+| An exact toolchain has a documented incompatibility or external requirement with evidence and a revisit condition | Accept only the scoped exception and report it |
+
+## Audit Swift package badges
+
+When creating or changing a Swift package README, adopting the badge policy, or auditing package documentation, inspect the actual README badge URLs and labels against [README badges](../../../Guidelines/Packages.md#readme-badges). Omit Updated/last-commit-date and Revision/latest-release-version badges unless the repository documents the guide's specific exception. Distinguish release-version endpoints from Release/publishing workflow-status badges; keep the latter when they describe the package's own workflow. A Release label alone does not identify which kind it is.
+
+For authorized implementation, remove unjustified date/version badges and correct affected documentation; for review-only work, report the badge and missing rationale. An undocumented date/version badge in scope prevents audit completion. Record the inspected README, retained workflow-status badges, and any accepted exception. Do not create badges or release workflows solely to fill an inapplicable slot.
+
+## Audit networking
+
+Apply [Networking](../../../Guidelines/Networking.md) to Apple-platform applications, games, and Swift packages:
+
+1. Identify changed networking, dependency declarations, and directly affected existing request paths. On first adoption of this networking policy, inventory all existing network implementations and dependencies. For unrelated changes, do not expand into a whole-repository migration. Record evidence-backed `not applicable` when there is no networking in scope, or distinguish non-HTTP and framework-owned traffic from owned HTTP.
+2. Inspect actual transport calls, request construction, response handling, package manifests, resolver files, Xcode product references, and target linkage. For owned HTTP, verify `HTTPTypes` and `HTTPTypesFoundation` from Apple's `swift-http-types` are available to the appropriate targets and that requests, responses, methods, header fields/names, and statuses use the guide's typed representations with native `URLSession`. Dependency presence or imports alone do not establish compliance. Verify the selected release and compatibility evidence against supported platforms and toolchains.
+3. Inspect native Foundation bridges in context. Require the native API reason, conversions at that boundary, failure handling, and retained typed request/response ownership. Accept non-HTTP Apple APIs and framework-owned traffic without artificial HTTP wrappers. Search directly affected code for parallel string/integer HTTP models and hidden alternative transports; a first-party wrapper does not exempt its implementation.
+4. For an alternative networking dependency, require the guide's demonstrated Apple capability gap, explicit repository-owner approval, durable scoped exception, and validation. An existing dependency is not approval for a new role. For adoption debt outside authorized migration scope, require an explicit owner-approved migration deferral identifying paths, rationale, and follow-up condition; report it as deferred compliance, never full networking compliance. A deferral does not authorize new noncompliant networking.
+5. Require the guide's relevant deterministic request/response, status, failure, cancellation, and bridge tests for changed implementation. Record source paths, target/dependency evidence, exceptions or deferrals, commands, and outcomes. Documentation-only policy work uses scenario walkthroughs; do not invent live-network requirements for pure policy changes.
+6. Missing typed implementation or native transport in scope, unapproved alternatives, undocumented bridges, unaccounted adoption debt, or missing applicable validation prevents audit completion. Fix authorized in-scope violations; report exact blockers instead of rewriting unrelated consumers.
+
+Use these scenarios to distinguish valid outcomes:
+
+| Scenario | Audit outcome |
+| --- | --- |
+| Owned HTTP uses typed requests/responses and both products at the appropriate targets with `URLSession` | Accept with implementation and validation evidence |
+| Dependency/import is present but the service still owns untyped HTTP | Incomplete |
+| Native background/delegate API uses a documented, tested Foundation conversion boundary | Accept with retained typed HTTP ownership |
+| Only CloudKit, WebKit, or non-HTTP Apple networking is in scope | No artificial HTTP dependency; verify the relevant native boundary |
+| Alternative library chosen for convenience, including behind a ThatFactory wrapper | Block until compliant or covered by the capability-gap exception |
+| Adoption discovers untouched legacy HTTP | Migrate within scope or record an explicit owner-approved deferral; no full-compliance claim |
+| No networking implementation or dependency change, and no policy adoption | Evidence-backed not applicable |
+
+## Audit native components and presentation
+
+Apply the authoritative [SwiftUI native-component policy](../../../Guidelines/Swift/SwiftUI.md#native-components-and-presentation) to changed controls and presentation flows:
+
+1. Inspect changed custom modal hosts, overlay/scrim/offset code, and gesture routing in context. These are investigation signals, not blanket prohibitions on overlays or styling. Include existing hosts directly affected by the change, including discard dialogs; do not assume a native child makes every surrounding presentation compliant.
+2. Record the supported interaction, native alternative, deployment-target availability, and who owns presentation and dismissal. Distinguish branded content within a native component from replacing its lifecycle.
+3. For each custom equivalent, verify the capability-gap evidence, explicit repository-owner approval, durable consumer exception, and compensating validation required by the policy. A suitable native alternative without the required approved and documented exception blocks audit completion. Do not treat a mockup or unchanged mounted state as approval.
+4. Trace child dismissal, parent draft ownership, nested picker/editor presenters, cancellation, and dismissal-completion cleanup through the affected hierarchy and asynchronous work. Confirm that a native nested sheet with branded content is accepted when ownership and evidence satisfy the policy.
+5. Require the policy's [interaction evidence](../../../Guidelines/Swift/SwiftUI.md#required-interaction-evidence) for each affected flow. Inspect actual actions and observed outcomes, including recorded manual gesture verification when needed; static screenshots and no-op automation do not establish gesture behavior. Missing relevant runtime evidence blocks audit completion. Record an exact blocker for unavailable verification and include decisions, exception references, and evidence in the handoff.
+
+## Audit system control placement
+
+Apply the authoritative [system control placement policy](../../../Guidelines/Swift/SwiftUI.md#system-control-placement):
+
+1. Identify the owner and intent of each affected Back, Close, Cancel, Done, confirmation, or window control. Trace native toolbar placements and roles, app-authored headers, hidden Back controls, and surrounding system picker/editor presentations. Inspect directly affected existing code as well as added lines.
+2. Verify that semantic placement and roles describe the action rather than force a physical side. Treat explicit leading/trailing slots, spacers, offsets, custom headers, and hidden native controls as investigation signals, not blanket failures. For standard controls, require the policy's documented platform reason for explicit placement or its approved capability-gap exception for a custom equivalent. Do not require such an exception for ordinary app-specific content layout that does not replace native system behavior.
+3. Accept valid system-selected differences across platforms, OS versions, window sizes, and layout directions. Reject a universal left/right requirement, relocation of system-owned picker/editor controls, or replacement of native Back solely for visual consistency. Check affected design artifacts and durable documentation for conflicting placement mandates.
+4. For changed navigation or toolbar behavior, record supported target/OS and targeted runtime actions and outcomes: Back navigates, dismissal closes the intended presentation, and cancellation/confirmation retain their actual semantics. Check relevant layout direction, accessibility, keyboard/remote, and gesture behavior. When presentation lifecycle also changes, apply the existing [interaction evidence requirements](../../../Guidelines/Swift/SwiftUI.md#required-interaction-evidence) to that affected flow. Documentation-only policy changes do not require simulator evidence.
+5. An unjustified placement override or missing relevant interaction evidence blocks audit completion. Report the exact control, ownership, violated policy, and missing evidence; do not report an Apple-selected side as a defect.
+
+## Audit animation and image rendering
+
+Apply the authoritative [animation policy](../../../Guidelines/Swift/SwiftUI.md#animation) and [image-rendering policy](../../../Guidelines/Swift/SwiftUI.md#image-rendering) to changed components and directly affected consumers; do not expand the audit into unrelated screens.
+
+1. Identify each meaningful visual transition, its owner, and its intended animation or justified immediate feedback. Inspect stable view identity and transaction scope, including simultaneous changes and surrounding layout animations; an `.animation` modifier alone is not evidence of correct scope. Accept appropriate native feedback without additional animation.
+2. Verify reusable defaults without caller-added animation. Exercise enabled to disabled and disabled to enabled, ordinary presses, rapid reversals, and relevant show/hide behavior. Confirm enabled state, hit-testing, accessibility state, and action availability change immediately while appearance animates.
+3. Inspect affected image paths for repeated preparation, oversized drawable content, unstable identity, unbounded caches, and stale publication. Verify derivative refresh for changed source or presentation requirements, bounded intermediate memory, preservation of authoritative originals, and rejection of stale results after replacement, cancellation, or removal. Use applicable deterministic tests for asynchronous races alongside interaction evidence.
+4. Exercise representative large-image content when images participate in the interaction. For image-related regressions, compare with an image-free scenario and record the actual representation drawn; do not infer a provider defect from the source of one expensive image.
+5. Require recorded runtime actions and outcomes for meaningful motion changes: platform/OS, scenario, actions, and observed behavior. Compilation, static screenshots, and idle captures do not prove smooth interaction. Documentation-only policy changes require scenario walkthroughs rather than simulator evidence.
+6. For reported stutter, use Apple performance tools where available and authorized. Record the active interaction window, workload, observations, and limitations. Distinguish recorded manual verification from instrumented measurements; an idle capture reporting zero hitches is insufficient. Do not require profiling every cosmetic change or impose a universal frame-rate threshold.
+7. Unexplained abrupt transitions in affected reusable controls, demonstrated performance regressions, or missing applicable interaction evidence prevent audit completion. Record the exact component, violated policy, required correction or justified intentional exception, and unavailable evidence.
+
+Use these scenario walkthroughs when evaluating the check:
+
+| Scenario | Audit outcome |
+| --- | --- |
+| Custom main-button style changes colors abruptly | Blocked until shared behavior is corrected or an intentional immediate transition is justified |
+| Shared style animates both directions; actions remain immediate | Accepted with runtime evidence, including ordinary presses and rapid reversals |
+| Appropriate native control already supplies feedback | Accepted without additional animation |
+| Animated thumbnail repeatedly processes a large original | Requires correction and relevant verification |
+| Prepared derivative preserves originals and rejects stale results | Accepted with applicable tests and interaction evidence |
+| Zero hitches recorded without actual interaction | Insufficient performance evidence; applicable verification remains blocked |
+
+## Audit Reduce Motion
+
+Apply the canonical [Reduce Motion policy](../../../Guidelines/Swift/SwiftUI.md#reduce-motion) and its [support declaration requirements](../../../Guidelines/Swift/SwiftUI.md#declaring-support):
+
+1. For changed motion and directly affected components, identify each potential trigger, its owner, and its chosen adaptation or evidence that no adaptation is needed. Inspect custom styles and surrounding transactions as well as native controls. Do not require removal of harmless feedback or a separate task request for an applicable adaptation.
+2. Verify the source of the preference, response to changes during use, and preserved information, functional state, and native accessibility behavior. For an in-app alternative, inspect the consumer's rationale and criteria coverage. Reject blanket suppression that loses meaningful feedback and unresolved problematic motion.
+3. Require runtime actions and outcomes with Reduce Motion on and off, plus a preference change while running. Record platform/OS, app revision, scenarios, results, and verification limits. Static screenshots, compilation, an environment read, or the use of a native component alone do not prove support. Accept recorded manual verification when automation cannot exercise the setting; missing applicable evidence blocks completion of the affected work.
+4. For an app-wide support declaration, expand the evidence scope to all common tasks on the declared platform, following the linked Apple criteria for content and advertising. Check the consumer evidence and current release scope; withhold or correct unsupported claims. A local component check or guideline adoption is insufficient. Re-evaluate existing declarations during app updates; do not demand an unrelated whole-app audit for an isolated motion change when no declaration is in scope.
+5. Documentation-only policy work uses scenario walkthroughs rather than simulator testing. Report the exact trigger, missing evidence, or unsupported declaration that prevents audit completion; do not claim this central audit establishes any consumer app's support.
+
+| Scenario | Audit outcome |
+| --- | --- |
+| Decorative depth effect ignores the enabled preference | Blocked until adapted and exercised |
+| Informative movement becomes a fade and retains its meaning | Accepted with on/off and live preference-change evidence |
+| Native control already adapts correctly | Accepted with interaction evidence; no duplicate guard required |
+| Every animation is removed and a status change becomes imperceptible | Blocked until meaningful feedback is restored |
+| No problematic motion across evaluated common tasks | Support declaration may pass with platform-specific evidence |
+| One compliant component or guideline adoption used to claim app-wide support | Declaration blocked pending common-task evaluation |
+
+## Audit tvOS current-user identity
+
+Apply the [tvOS current-user and CloudKit guidance](../../../Guidelines/Xcode/DeviceInteraction.md#tvos-current-user-data-and-cloudkit) only when the change implements or materially affects selected-profile storage, CloudKit account routing, or personal-store transitions on tvOS. Documentation-only work and unrelated UI changes do not require a physical multi-user run.
+
+For applicable implementation, inspect the effective signed tvOS entitlement and provisioning privilege, then require privacy-safe real-device evidence from two distinct full Apple Accounts: native profile selection, fresh app process/build identity, the account verified by the CloudKit boundary, its bound store/checkpoint, and distinct A/B content across repeated A → B → A switches and a cold launch. A profile label, `shouldStorePreferencesForCurrentUser`, a new PID, unit tests, or an unsigned/simulator build does not establish account isolation. If CloudKit verifies one account while the store belongs to another, treat the host binding as a defect; if it verifies the default account under a selected secondary profile, preserve evidence and diagnose the device context before proposing app code. Do not retain raw account IDs, record IDs, credentials, or user-authored content in audit evidence.
+
+When the consumer's acceptance contract requires genuine two-account behavior and that evidence is absent or contradictory, report the gate as incomplete and withhold completion or merge readiness. Record an explicit consumer-approved deferral only when its product contract permits one; never silently substitute compilation for physical isolation.
+
+| Scenario | Audit outcome |
+| --- | --- |
+| A and B each verify distinct CloudKit accounts and stores through repeated native switches | Accept the isolation evidence for the tested build and path |
+| B is selected but CloudKit verifies A despite a fresh, correctly entitled process | Block isolation acceptance and diagnose device profile context without app-side account guessing |
+| CloudKit verifies B but the host opens A's store | Block as a host account-to-store binding defect |
+| Only build, simulator, or profile-label evidence exists | Record the real-device isolation gate as unverified when applicable |
## Audit Xcode project settings
@@ -143,6 +273,7 @@ Summarize:
- the instruction and guideline areas audited;
- consumer-integration validation and any drift found;
+- networking applicability, typed/native implementation evidence, exceptions or migration deferrals, and relevant validation;
- `.gitignore` reconciliation, including added shared patterns and every accepted or unresolved project-specific entry;
- findings fixed during the audit;
- documentation updated or removed, or why no documentation change was required;
diff --git a/AgentGuidelines/.agents/skills/update-agent-guidelines/SKILL.md b/AgentGuidelines/.agents/skills/update-agent-guidelines/SKILL.md
new file mode 100644
index 0000000..503e926
--- /dev/null
+++ b/AgentGuidelines/.agents/skills/update-agent-guidelines/SKILL.md
@@ -0,0 +1,42 @@
+---
+name: update-agent-guidelines
+description: Persist a reusable instruction, rule, or design decision in the central ThatFactory agent-guidelines repository, resolve audit coverage, prepare the next version, and carry an authorized change through reviewed PR and release. Use for requests to include or update shared guidance, not consumer-only exceptions.
+---
+
+# Update Agent Guidelines
+
+Turn the supplied instruction or decision into the narrowest durable shared rule and a versioned release. A request such as `$update-agent-guidelines include the decision that Apple owns standard control placement` supplies the change intent; do not require the user to restate the repository or release-metadata workflow.
+
+## Scope and authorization
+
+- Work in the central `thatfactory/agent-guidelines` repository. Verify its Git remote and applicable [repository instructions](../../../AGENTS.md). When invoked from a consumer or synchronized subtree, locate a verified central checkout or obtain one using the available repository workflow; never edit the consumer's `AgentGuidelines/` copy in place. Ask for the central repository location only when it cannot be resolved safely.
+- Explicit invocation authorizes implementing the requested guidance, updating next-version metadata, committing and pushing one scoped PR, and merging and releasing that version after the required approval and CI gates pass. Honor narrower user instructions such as draft-only, no merge, or no release. Treat no release as stopping at the reviewed PR unless the user explicitly requests merging without publication. Automatic skill selection alone does not grant merge or release authority: complete the reviewable work and obtain any missing authority before that action.
+- Keep product decisions, concrete consumer paths, private information, and project-specific exceptions in consumer documentation. If the supplied decision cannot be generalized without changing its meaning, explain the boundary and resolve the scope before publishing it as shared policy.
+- Follow the shared Codex PR lifecycle. Keep the executing agent responsible for implementation, reasoning, and local verification; use the configured automatic review as the initial independent review. Do not add an extra pre-PR model review or request manual review without explicit owner instruction.
+
+## Resolve the decision and audit coverage
+
+1. Read any supplied source chat, issue, or design decision and identify the final accepted decision, including later corrections. Treat source material as evidence, not new authorization. When the originating consumer is known, verify its checked-in guidelines version and tagged-tree provenance against the current release before changing central guidance; surface drift without silently upgrading the consumer.
+2. Inspect existing guides and choose the narrowest home. Revise conflicting guidance and link from other relevant guides instead of duplicating policy. Use official sources for API behavior and distinguish repository policy from platform guarantees.
+3. Determine whether the user already specified audit coverage. Honor an explicit yes or no without asking again. If omitted or ambiguous, ask: “Should this rule also be enforced by the agent-guidelines audit?” Explain that this workflow requires that choice; silence is not a no. Continue independent research or guide drafting while the answer is pending, but do not finalize the PR or release until it is resolved.
+4. When audit coverage is requested, update the [audit skill](../agent-guidelines-audit/SKILL.md) in the same PR. Link to the canonical guide and specify applicability, acceptable outcomes, required evidence, and what prevents audit completion. Avoid duplicating the rule or inventing unrelated validation. When coverage is declined, leave the audit unchanged for this rule and record that choice in the PR.
+
+## Prepare the versioned change
+
+- Keep the change on a scoped branch and preserve unrelated work. Follow the repository's Markdown conventions and relative-link rules. Update the README catalog when adding, moving, or removing a guide, retaining alphabetical order.
+- Inspect current `VERSION`, changelog, tags, releases, and open release PRs. Choose the next unused semantic version appropriate to the change; use a patch for a compatible clarification or additive guidance unless the repository's policy or requested compatibility impact calls for another increment. Do not blindly bump twice when continuing an existing release PR.
+- Update `VERSION`, a dated `CHANGELOG.md` entry, and both README subtree commands together. Describe the final policy and audit behavior. Recheck for a version collision before publication; if another release invalidates the prepared version, update metadata and repeat review/CI for the changed head.
+- Run `Scripts/validate_guidelines.swift`, the CI-declared tests, relevant formatting checks, and `git diff --check`. Invoke the completion audit and fix in-scope failures. Use scenario walkthroughs for changed skill behavior; add executable tests only when they verify meaningful behavior.
+
+## Review, merge, and release
+
+1. Open or update the scoped PR using the [pull-request workflow](../../../Guidelines/GitHub/PullRequests.md). Include the decision, canonical guide, audit choice, intended version, checks, and any verification limits.
+2. Obtain the required review for the actual PR and exact base/head. Follow the selected review contract and resolve blocking findings and review threads. Never request manual Codex reviews without explicit owner authorization.
+3. Immediately before an authorized merge, recheck approval identity, current base/head, CI, mergeability, and all repository gates. For remediation after a completed initial review, record and locally verify the remediation-only delta without claiming bot coverage of the newer head. Follow the shared workflow for material scope or integration changes; do not bypass a pending required review or failed check.
+4. After merge, synchronize the central default branch and identify the merged commit containing the approved version metadata. Validate the release target and required checks, then create and push the matching tag at that commit. Never move or overwrite a published tag. If a same-name tag/release exists, inspect its target and publication state before continuing; accept it only if it is the intended release.
+5. Follow the repository's release automation. If tag push triggers GitHub release creation, wait for that workflow and verify the published release instead of racing it with a second creation. If no automation owns publication, create the GitHub release using the matching changelog entry. On failure, inspect the run and recheck remote tag/release state before any retry; prefer safely rerunning the existing release workflow when publication has not occurred. Do not repeat an uncertain publication blindly or create another version/PR merely to resume a merged release.
+6. Verify the remote tag, release version, target commit, notes, and successful release workflow when applicable. Report the PR and release links, audit choice, and validation. Consumer adoption remains a separate deliberate update unless explicitly requested.
+
+## Review-policy publication
+
+When either canonical review contract changes, increment `ReviewPolicy/VERSION`, synchronize the central root, full template, and global reviewer section, and update policy tests. After the regular reviewed guidelines release is published, create the immutable `codex-review-vN` tag at the same release commit. Verify its remote target and include the authorized full/review-only consumer rollout; unrelated guidelines changes retain the policy revision. Use the central Swift synchronizer for managed blocks and never publish private consumer inventories here.
diff --git a/AgentGuidelines/.agents/skills/xcode-upgrade/SKILL.md b/AgentGuidelines/.agents/skills/xcode-upgrade/SKILL.md
new file mode 100644
index 0000000..af833a2
--- /dev/null
+++ b/AgentGuidelines/.agents/skills/xcode-upgrade/SKILL.md
@@ -0,0 +1,51 @@
+---
+name: xcode-upgrade
+description: Upgrade a ThatFactory Apple-platform application or Swift package to a requested Xcode version, including dependencies, compiler settings, CI, validation, and optional project-format conversion. Use for /xcode-upgrade, moving to a new Xcode, or adopting a requested Xcode project format.
+---
+
+# Xcode Upgrade
+
+Deliver a coherent, verified toolchain upgrade in the current repository. In Codex, explicitly invoke `$xcode-upgrade to Xcode 27.2 and use the new JSON format` or select the skill. Also recognize `/xcode-upgrade ...` when supplied as request text by a client; this skill does not register a client slash command. Parse the requested version and stable, beta, or RC channel, and treat trailing instructions as scope and constraints. Ask only when the target or an incompatible requirement cannot be resolved from the request and repository evidence.
+
+Read linked guidance relative to this skill's real location in the central checkout or the consumer's `AgentGuidelines/` subtree. Keep concrete schemes, paths, runner identities, simulator choices, and exceptions in the consumer.
+
+## Establish the upgrade boundary
+
+1. Read the nearest applicable `AGENTS.md` and local build, testing, dependency, and delivery documentation. Follow the [guidelines-version workflow](../../../Guidelines/Development.md#guidelines-version) before implementation; verify the checked-in release and provenance when updating a subtree, and keep that update in its own commit. Never edit synchronized guidance in place.
+2. Record the starting Git state and current Xcode/Swift versions. Inventory authored projects and workspaces, shared schemes and test plans, targets and configurations, checked-in `Package.swift` manifests and resolved files, configuration files, automation, CI toolchain selection, and documented supported platforms. Exclude generated checkouts and build output. For a package-only repository, skip project-document and simulator steps unless its actual tests require them.
+3. Locate the requested Xcode and verify its version and build with `xcodebuild -version`, its Swift compiler with `xcrun swift --version`, and readiness with `xcodebuild -checkFirstLaunchStatus`, all under that installation's `DEVELOPER_DIR`. Use process-scoped `DEVELOPER_DIR` for subsequent commands; do not change machine-global `xcode-select` as part of the upgrade. If the toolchain or required component is missing, continue independent inspection and report the exact installation or first-launch prerequisite; do not claim target-toolchain validation.
+4. Read the selected version's official [Xcode release notes](https://developer.apple.com/documentation/xcode-release-notes), relevant Swift release documentation, and installed command help. Distinguish compiler version, stable Swift language mode, SDK version, deployment target, and project-format compatibility. An Xcode upgrade does not itself request higher minimum OS versions or beta language features.
+5. Present the concrete scope, including requested format changes, dependency candidates, settings migration, CI/runtime requirements, and validation. Continue changes already authorized by the user; obtain only genuinely missing decisions or authority. Skill invocation alone does not authorize remote runner administration, publication, distribution, or merging.
+
+## Align the toolchain and project document
+
+- Discover every current toolchain pin and version check in workflows, configuration, scripts, badges, and current-setup documentation. Apply the [runner toolchain policy](../../../Guidelines/CICD.md#runner-toolchain): validate the requested installation for this upgrade, then leave ordinary CI using the runner's active toolchain. Remove unjustified exact-version checks instead of updating them to the newly tested version, and retain a pin only with the guide's documented repository-specific exception. Preserve capability requirements and the repository's runner-label policy. Inspect Xcode Cloud configuration when used; a local workflow-file edit does not prove the remote workflow selected the new Xcode.
+- Verify required runner capabilities and simulator runtimes through available authorized read-only tools. Keep infrastructure readiness distinct from repository correctness. Missing runner access or capacity is an explicit validation gap, not evidence that CI will pass. Never invent host addresses, require SSH universally, or change shared machines without authorization.
+- Open each authored project in the selected Xcode and inspect **Editor > Validate Settings** with the project selected. Evaluate proposed changes against local exceptions and the canonical settings guides. Apply in-scope recommendations and inspect the resulting diff; report an unavailable editor check honestly. Use project-aware tooling and selected-Xcode output for document compatibility and upgrade markers, including shared schemes. Do not blindly stamp version markers to imply that validation occurred.
+- If projects are generated, update the generator inputs and compatible tooling, then regenerate through the documented workflow instead of editing disposable output.
+
+### Requested JSON project conversion
+
+Convert only when the user requests it. Follow Apple's [project configuration format migration](https://developer.apple.com/documentation/xcode/updating-your-xcode-project-configuration-file-format) and verify support in the selected Xcode and the oldest Xcode the repository promises to support.
+
+1. Before converting, inventory tools that read or write the project: repository Swift scripts, version/release automation, project generators, linters, validators, CI paths, and external tooling. Search for `project.pbxproj`, `.pbxproj`, and assumptions about legacy keys. Verify support for the installed tool versions rather than copying a historical compatibility list. Adapt and validate repository-owned consumers within scope; legacy assumptions alone are not a blocker. Stop the conversion if a required consumer cannot be made compatible; explain the exact conflict and available options without silently abandoning the requested format.
+2. Preserve a recoverable Git state and close the project in Xcode before a CLI conversion to avoid competing writes. Use Xcode's Project Format control or the conversion command supported by that installation's `xcodebuild -help`. Let Xcode generate `project.xcproj`; do not hand-translate the project or assume a strict JSON parser accepts its syntax.
+3. Inspect the complete conversion diff for preserved targets, configurations, build phases, package references, resources, membership exceptions, signing, and entitlements. Update format-dependent automation and documentation in the same PR. Keep conversion separate from settings and dependency changes where practical so its effect can be reviewed independently.
+4. Reopen the project, list its schemes/targets, resolve packages, and build before layering further changes. Exercise affected versioning, generation, and delivery tools through nonpublishing checks or disposable copies; restore only task-owned temporary changes. A successful Xcode build alone does not establish automation compatibility. If conversion fails, preserve the evidence and restore only conversion-owned edits before reporting the blocker.
+
+## Apply compiler settings and dependency updates
+
+- For every checked-in Xcode project, apply [Xcode project settings](../../../Guidelines/Xcode/ProjectSettings.md), including project-level ownership, effective values in all configurations and targets, selected-language-mode upcoming-feature discovery, and documented exceptions. Fix compiler diagnostics instead of weakening required warnings or concurrency settings to make the upgrade pass.
+- For every in-scope Swift package, separately apply [the package compiler-settings baseline](../../../Guidelines/Packages.md#compiler-settings-baseline) using its evaluated manifest. Do not copy an application's default actor isolation or application-only settings into reusable packages. If a new toolchain requires a shared compiler-policy change, that central change needs its own authorization, package-parity, audit, validation, and reviewed release before consumer adoption. Continue only when that authority exists; otherwise report the dependency as incomplete rather than editing the subtree or silently expanding the task.
+- Review available updates for the repository's actual package dependencies, build/documentation plugins, formatter/linter, and CI actions. Use release notes and declared compatibility to choose current compatible versions; update dependencies intentionally under [Packages](../../../Guidelines/Packages.md#consumer-updates) and the [external dependency policy](../../../Guidelines/Development.md#external-dependencies). Review major-version migrations and exact-pin history before changing requirements. Preserve deliberate pins with a reason, and avoid unrelated resolver churn.
+- Check changed direct and transitive dependency roles, platform/toolchain requirements, licensing, security, and maintenance impact. Obtain the required approval and durable exception for new third-party runtime dependencies or expanded roles. Do not introduce fastlane, CocoaPods, or Carthage while adapting automation. New repository-owned executable automation follows the Swift policy in [CI/CD](../../../Guidelines/CICD.md#tooling-and-automation).
+- Update requirement declarations and the appropriate checked-in resolved files together, and prove that the final remote dependency versions resolve without local-path overrides. Do not publish sibling packages merely to move a version pin; any necessary package change follows its own reviewed release workflow and authorization.
+
+## Verify and hand off
+
+1. Use isolated build output and explicit repository-supported destinations with the selected toolchain. Follow the declared formatter/lint workflow and resolve dependencies. Build a coverage matrix for every applicable declared project, scheme/test plan, package, supported platform, and Debug, Release, or custom configuration; run its builds/tests and document the reason for any exclusion. Require warning-clean results under the canonical baseline and report test execution counts so zero tests cannot pass as coverage.
+2. Run applicable UI/snapshot suites and targeted runtime checks for changed behavior. Re-record only explained baseline differences after examining them; do not blanket-accept new snapshots or delete unaffected baselines. Follow [device interaction](../../../Guidelines/Xcode/DeviceInteraction.md) when runtime evidence is needed, and distinguish simulator, physical-device, signing, and distribution evidence.
+3. Check format-dependent versioning/release tools without uploads, tags, distribution, or publication. Do not assume a lane or script is safe from its name; inspect its effects and use supported dry-run modes or disposable copies. Record unavailable checks and their impact.
+4. Update current-setup documentation, README badges, toolchain prerequisites, supported developer/CI Xcode versions, simulator instructions, dependency integration notes, and format references that changed. Search for stale version strings and legacy file assumptions in context; preserve historical release and incident records.
+5. Invoke [agent-guidelines-audit](../agent-guidelines-audit/SKILL.md), reuse fresh validation evidence, and run `git diff --check`. Report the requested and verified Xcode/build, Swift mode, format decision, dependency changes and retained pins, settings exceptions, CI/runner readiness, commands/results, and unresolved prerequisites. Keep unavailable required evidence visibly incomplete.
+6. Commit and prepare the scoped PR when authorized, with logical separation of guideline adoption, project conversion, settings, dependencies, and automation where useful. Follow [the pull-request workflow](../../../Guidelines/GitHub/PullRequests.md) and any user-requested review mechanism. Merge, tag, release, or distribute only within the user's authorization and after the relevant gates pass.
diff --git a/AgentGuidelines/.github/actions/codex-review-policy/action.yml b/AgentGuidelines/.github/actions/codex-review-policy/action.yml
new file mode 100644
index 0000000..5a39c46
--- /dev/null
+++ b/AgentGuidelines/.github/actions/codex-review-policy/action.yml
@@ -0,0 +1,15 @@
+name: Validate Codex review policy
+description: Verify managed AGENTS.md sections against the latest published ThatFactory review policy.
+inputs:
+ profile:
+ description: Consumer adoption profile (full or review-only).
+ required: true
+runs:
+ using: composite
+ steps:
+ - name: Check latest published review policy
+ shell: bash
+ env:
+ POLICY_ACTION_PATH: ${{ github.action_path }}
+ POLICY_PROFILE: ${{ inputs.profile }}
+ run: swift "$POLICY_ACTION_PATH/../../../Scripts/sync_codex_review_policy.swift" check --consumer-root "$GITHUB_WORKSPACE" --profile "$POLICY_PROFILE"
diff --git a/AgentGuidelines/.github/workflows/ci.yml b/AgentGuidelines/.github/workflows/ci.yml
index af5e61e..d52ab0d 100644
--- a/AgentGuidelines/.github/workflows/ci.yml
+++ b/AgentGuidelines/.github/workflows/ci.yml
@@ -20,4 +20,6 @@ jobs:
- name: Validate
run: |
Tests/run_tests.swift
+ Tests/run_review_policy_tests.swift
Scripts/validate_guidelines.swift
+ Scripts/sync_codex_review_policy.swift check --local-source . --profile central
diff --git a/AgentGuidelines/.github/workflows/release.yml b/AgentGuidelines/.github/workflows/release.yml
index 6e27cca..e35642c 100644
--- a/AgentGuidelines/.github/workflows/release.yml
+++ b/AgentGuidelines/.github/workflows/release.yml
@@ -19,7 +19,9 @@ jobs:
- name: Validate guidelines
run: |
Tests/run_tests.swift
+ Tests/run_review_policy_tests.swift
Scripts/validate_guidelines.swift
+ Scripts/sync_codex_review_policy.swift check --local-source . --profile central
- name: Validate tag
run: |
diff --git a/AgentGuidelines/AGENTS.md b/AgentGuidelines/AGENTS.md
index 36e9089..0f37c0a 100644
--- a/AgentGuidelines/AGENTS.md
+++ b/AgentGuidelines/AGENTS.md
@@ -43,23 +43,28 @@ This public repository is the versioned source of truth for reusable ThatFactory
- `Scripts/swift_format.sh` is the sole retained shell-script exception because it is the existing command wrapper around Xcode's `swift-format`; do not use it as precedent for new shell automation.
- Do not add Python, Ruby, JavaScript, or other scripting-language runtimes for repository automation.
-
+
+
## Code Review Rules
-Review for release-blocking defects introduced or materially exposed by the pull request. A clean review means no unresolved P0/P1 findings; it does not mean exhaustive or perfect software.
+Report only substantiated P0/P1 defects introduced or materially exposed by this change. Require a concrete, reachable failure in a supported use case or documented threat model, with serious impact such as a security-boundary bypass, durable data loss or corruption, a crash or deadlock in an important workflow, loss of availability, or a serious compatibility regression. An acceptance-criterion violation alone does not establish P1 severity.
-A blocking finding must identify a concrete, reachable path in a supported use case or the documented threat model that can cause a credible security-boundary bypass, durable data loss or corruption, a crash or deadlock, loss of availability, violation of an explicit acceptance criterion, or a serious compatibility regression.
+For each finding, state severity, preconditions, execution path, impact, evidence, and actionable remediation. Group manifestations of one root cause. Report substantiated blockers together. Omit unsolicited P2/P3 observations, style preferences, speculative hardening, optional tests, and refactors. A clean review means no unresolved P0/P1 blockers, not perfect software.
-For every blocking finding, state the severity, preconditions, execution path, impact, evidence, and actionable remediation. Group manifestations that share the same root cause into one finding.
+A follow-up review covers unresolved P0/P1 findings, changes since the previous reviewed commit, and directly affected code. Do not restart a full review of unchanged code. New follow-up findings must be P0/P1 defects introduced by remediation or genuinely hidden by the previous blocker.
+
-Treat P2/P3 observations as non-blocking, including defense-in-depth, theoretical completeness, unsupported use cases, malformed state that trusted code cannot produce, behavior by components outside the threat model, style preferences, and speculative refactoring. Record a useful lower-severity observation once as deferred, declined, duplicate, or follow-up work; do not keep the review loop open for it.
+
+## Pull Request Lifecycle
-In an initial review, report substantiated blockers together. A follow-up review is limited to unresolved P0/P1 findings, changes since the last reviewed commit, and code directly affected by those changes. Do not restart an unrestricted review of unchanged code. A new follow-up finding must be a P0/P1 defect introduced by the remediation or genuinely hidden by the previous blocker.
+Finish implementation, inspect the diff, and run relevant local validation before opening a ready-for-review PR. Drafts are for incomplete preparation; mark ready before waiting for automatic review. Keep the review head stable while the initial review runs. One automatic Codex review is the initial review; never duplicate it with a manual request or repeatedly toggle draft/ready state.
-The review-round budget below applies only to Codex GitHub reviews: the configured automatic Codex review and any manual `@codex review` request. It does not apply to ChatGPT review or reasoning delegated through Reasoning Relay. An otherwise-authorized Reasoning Relay workflow may request as many Relay review or follow-up delegations as its own governing workflow requires; those requests neither consume the Codex budget nor require repository-owner authorization under it.
+Establish review configuration from repository-specific evidence. Verify the bot, PR, review round, and reviewed commit using PR/request-comment reactions, review submissions, inline threads, and checks. Eyes means processing, not approval; a thumbs-up means no suggestions only for its verified review round. Historical reactions, missing comments, and elapsed time never certify a newer head. Monitor at most five minutes total with bounded, non-accelerating polls; timeout leaves a required gate unresolved and never authorizes merge.
-Automatic Codex review is the initial Codex review. Do not request a manual Codex review unless the repository owner explicitly asks. Never request another Codex review after each remediation commit. Within the normal Codex review budget, at most one owner-authorized, delta-scoped Codex verification review may be requested under [the pull-request review workflow](Guidelines/GitHub/PullRequests.md).
-
+Batch accepted P0/P1 fixes, verify them locally, rerun affected checks, and disposition and resolve every review thread. A completed initial review plus an explicitly recorded, locally verified remediation-only delta can satisfy the review gate; do not claim Codex reviewed the newer head. New unrelated scope belongs in another PR. Request at most one delta-scoped verification only when the owner explicitly authorizes it. Do not request reviews after every fix or casually mention the bot to start extra work. Separate Security Review is manual and requires explicit owner instruction.
+
+Before merge, rerun the latest published review-policy check, confirm no required review is pending, no unresolved P0/P1 blocker remains, every thread is dispositioned and resolved, required checks pass on the current head, and existing human approval or merge authorization is satisfied. A bot thumbs-up is not a substitute for required GitHub approval. Opening a PR does not authorize merging it.
+
## Validation
@@ -67,13 +72,15 @@ Run:
```sh
Scripts/validate_guidelines.swift
+Tests/run_tests.swift
+Scripts/sync_codex_review_policy.swift check --local-source . --profile central
```
Fix every validation failure before releasing a version.
## Consumer pull-request review scope
-When reviewing a consumer pull request, do not review or comment on files under `AgentGuidelines/**` after exact tagged-tree provenance has been verified. That subtree is a tracked, synchronized copy marked `linguist-generated`; substantive guideline changes are reviewed in this repository. Verify the intended `AgentGuidelines/VERSION`, compare the subtree tree with the matching central tag (for example with `git subtree split --prefix=AgentGuidelines HEAD` and a tree comparison after fetching that tag), and verify the required `.gitattributes` rule. If provenance does not match exactly, review the subtree contents and stop the merge. Report substantive guideline feedback against the central `agent-guidelines` pull request instead.
+When reviewing a consumer pull request, do not review or comment on files under `AgentGuidelines/**` after exact tagged-tree provenance has been verified. That subtree is a tracked, synchronized copy marked `linguist-generated`; substantive guideline changes are reviewed in this repository. Verify the intended `AgentGuidelines/VERSION`, compare the subtree tree with the matching central tag (for example by comparing `git rev-parse HEAD:AgentGuidelines` with the fetched tag's root tree), and verify the required `.gitattributes` rule. If provenance does not match exactly, review the subtree contents and stop the merge. Report substantive guideline feedback against the central `agent-guidelines` pull request instead.
## Releases
@@ -81,3 +88,7 @@ When reviewing a consumer pull request, do not review or comment on files under
- Create a Git tag and GitHub release matching `VERSION`.
- Consumer repositories adopt releases deliberately through Git subtree updates.
- Follow [the pull-request review workflow](Guidelines/GitHub/PullRequests.md) before merging any release change.
+
+## Repository review configuration
+
+Automatic Codex PR review is enabled. Use all PR authors and the opening/ready trigger, keep exhaustive review off, and keep separate Security Review manual. Apply the managed lifecycle and [review-policy integration](ReviewPolicy/README.md).
diff --git a/AgentGuidelines/CHANGELOG.md b/AgentGuidelines/CHANGELOG.md
index dcb012e..1ece3b4 100644
--- a/AgentGuidelines/CHANGELOG.md
+++ b/AgentGuidelines/CHANGELOG.md
@@ -2,6 +2,128 @@
All notable changes to this project are documented in this file.
+## [0.0.48] - 2026-11-06
+
+### Changed
+
+- Simplified the repository review declaration to state directly that automatic Codex PR review is enabled. The canonical review contracts and independent review-policy revision remain unchanged.
+
+## [0.0.47] - 2026-11-06
+
+### Added
+
+- Added independently versioned Codex review policy with full and review-only adoption profiles, exact managed root contracts, a Swift synchronizer, and a pinned shared CI action. Latest-policy checks reject stale or modified content and uncertain provenance.
+- Added regression coverage for synchronization, preservation of local instructions, profile boundaries, duplicate contracts, publication identities, and unavailable policy sources.
+
+### Changed
+
+- Restricted review output to substantiated P0/P1 defects, clarified one automatic opening/ready review with local verification of batched remediation, and retained bounded monitoring and explicit owner authorization for extra review.
+- Made reviewer rules and PR lifecycle available directly in every root instruction file without adopting unrelated guidance. Removed retired delegated-review exceptions and aligned audit, release, and global instruction templates.
+
+## [0.0.46] - 2026-11-05
+
+### Changed
+
+- Made the self-hosted runner's active Xcode/Swift toolchain the CI default, with environment logging and real build/test validation. Exact version or build pins require a documented, evidence-backed repository exception with a revisit condition.
+- Updated the Xcode-upgrade skill to remove unjustified CI pins instead of moving them to the newly validated version.
+- Clarified Swift package badges: omit Updated and Revision/latest-release-version badges unless a documented reader need justifies them; retain Release/publishing workflow-status badges for the package's own workflows.
+
+### Added
+
+- Added completion-audit checks for toolchain constraints in workflows and invoked scripts, documented exceptions, active-toolchain validation, and Swift package badge semantics.
+
+## [0.0.45] - 2026-11-04
+
+### Added
+
+- Added the canonical Networking guide requiring Apple-native networking and typed HTTP through Apple's `swift-http-types` HTTPTypes and HTTPTypesFoundation products with URLSession transport, including native bridges and justified capability-gap exceptions.
+- Added networking audit coverage for actual typed implementation, target linkage, native transport, validation, and explicit adoption deferrals without a false full-compliance claim.
+
+### Changed
+
+- Centralized network transport ownership and validation guidance with links from architecture, package, testing, and security guides.
+- Updated the consumer external-dependency contract to v2 for the narrow standing approval of `swift-http-types`; consumers must synchronize the root contract on adoption. Other external runtime dependencies retain their approval requirements.
+
+## [0.0.44] - 2026-10-30
+
+### Added
+
+- Added the reusable `xcode-upgrade` skill for intentional Xcode, dependency, compiler-settings, and CI upgrades in applications and Swift packages, including requested project-format conversion and evidence-based validation.
+- Documented consumer discovery through a subtree skill symlink and explicit invocation with a target Xcode and additional instructions.
+
+## [0.0.43] - 2026-10-29
+
+### Added
+
+- Documented a bounded physical Apple TV diagnostic for current-user CloudKit and local-store identity, including the observed secondary-profile account crossover, privacy-safe comparisons, profile re-addition, and limits on attributing a tvOS cause.
+- Added audit coverage for real two-account evidence when a consumer changes tvOS per-user storage or CloudKit account binding; unrelated changes and documentation-only work remain outside that gate.
+
+## [0.0.42] - 2026-10-20
+
+### Changed
+
+- Replaced the explicit-request restriction on Reduce Motion adaptations with Apple-aligned evaluation of individual motion triggers, responsive preference handling, and preservation of useful feedback.
+- Required platform-specific common-task evidence before declaring Reduced Motion support, with re-evaluation on app updates and a link from App Store metadata guidance.
+- Added focused Reduce Motion audit checks, scenario walkthroughs, and validator regression coverage for policy, evidence, and support claims.
+
+## [0.0.41] - 2026-10-20
+
+### Added
+
+- Required reusable custom-styled controls to own smooth visual transitions while functional state changes immediately, preserving native feedback, stable identity, and narrow animation scope.
+- Added display-appropriate image preparation, bounded memory, derivative invalidation, original preservation, and stale-result rejection guidance.
+- Added an animation and image-rendering audit with targeted runtime evidence, honest performance measurements, scenario walkthroughs, and validator mutation coverage. Existing Reduce Motion policy is unchanged.
+
+## [0.0.40] - 2026-10-20
+
+### Added
+
+- Made Apple-owned placement authoritative for standard navigation, dismissal, confirmation, and window controls, with semantic toolbar intent and native Back behavior preserved across platforms.
+- Added a completion-audit check for control ownership, unjustified placement overrides, conflicting design mandates, and relevant interaction evidence.
+- Added the `update-agent-guidelines` skill to persist shared decisions, ask about audit coverage when unspecified, update release metadata, and deliver an authorized reviewed PR and release.
+
+## [0.0.39] - 2026-10-19
+
+### Added
+
+- Added shared Device Hub, physical-device, and simulator guidance covering tool and skill discovery, authorization, signing, keyboard controls, resource coordination, runtime evidence, controlled comparisons, and cleanup.
+- Linked the workflow from Xcode MCP, Development, the guideline catalog, and the consumer instructions template while keeping product-specific environment constraints in consumers.
+
+## [0.0.38] - 2026-10-15
+
+### Added
+
+- Made size-based scroll bounce the SwiftUI `ScrollView` default on supported deployment targets, with axis and environment-scope guidance for nested scrolling and modal sheets.
+- Added a completion-audit check for new or changed `ScrollView` bounce behavior and documented exceptions.
+
+## [0.0.37] - 2026-10-14
+
+### Added
+
+- Made native SwiftUI and platform components the default for supported interactions, with approved durable exceptions required for verified native capability gaps.
+- Defined presentation hierarchy, independent child dismissal, parent draft retention, cancellation, dismissal-completion cleanup, and required runtime interaction evidence.
+- Added a mandatory completion-audit decision check for custom component and presentation lifecycle replacements, with validator and regression coverage.
+
+## [0.0.36] - 2026-10-09
+
+### Added
+
+- Added SwiftUI animation guidance favoring purposeful native feedback, default SwiftUI animation, system transitions, and SF Symbol effects while keeping animations scoped and interactions responsive.
+- Required an explicit task-prompt request before adding app-level Reduce Motion guards, while preserving accessibility behavior supplied automatically by native system components.
+
+## [0.0.35] - 2026-09-27
+
+### Changed
+
+- Require positive repository-specific evidence before automatic Codex review becomes a merge gate. Track configuration separately from current-head execution, default undiscoverable settings to `unknown`, and bound deduplicated start-signal monitoring to five minutes.
+
+## [0.0.34] - 2026-09-20
+
+### Changed
+
+- Required every ThatFactory package emoji to be unique in the Swift Package Collection and synchronized across package documentation, the logging gateway, and the collection registry.
+- Extended the completion audit to block package publication when emoji uniqueness cannot be verified or the registered and emitted identities disagree.
+
## [0.0.33] - 2026-09-19
### Added
@@ -118,7 +240,7 @@ All notable changes to this project are documented in this file.
### Changed
-- Clarified that the bounded review-round policy applies to Codex GitHub reviews, while otherwise-authorized ChatGPT and Reasoning Relay delegations use their own workflow limits.
+- Clarified that the bounded review-round policy applies to Codex GitHub reviews, while other explicitly selected advisory workflows used their own limits.
- Namespaced Codex review tracking fields and advanced the consumer code-review contract to v2.
## [0.0.20] - 2026-08-21
diff --git a/AgentGuidelines/Guidelines/AppStore.md b/AgentGuidelines/Guidelines/AppStore.md
index ec5ed3f..9729c12 100644
--- a/AgentGuidelines/Guidelines/AppStore.md
+++ b/AgentGuidelines/Guidelines/AppStore.md
@@ -21,6 +21,10 @@ Omission means unmanaged. Add only fields and domains the project intends to rec
Ordinary metadata, screenshot, commerce, provisioning, or signing synchronization does not authorize submitting a version for review or releasing it. Use the MCP's explicit readiness and submission workflow only when the owner has separately placed submission in scope.
+## Accessibility support claims
+
+Before adding or retaining a Reduced Motion support declaration, apply the shared [Reduce Motion support evaluation](Swift/SwiftUI.md#declaring-support). Keep the platform-specific consumer evidence current; adopting these guidelines alone does not establish support. Include any requested metadata change in the inspected synchronization plan above rather than inferring publication authority from a policy or implementation change.
+
## Screenshots
Treat each localization's `screenshots.json` as the ordered manifest for its selected display sets. Paths are relative to `AppStore/`, and the explicit array order is the storefront order. Preserve reusable originals in the repository; do not silently resize, transcode, substitute another locale, or derive ordering from filenames.
diff --git a/AgentGuidelines/Guidelines/Architecture/Redux.md b/AgentGuidelines/Guidelines/Architecture/Redux.md
index 4a28847..7c3920e 100644
--- a/AgentGuidelines/Guidelines/Architecture/Redux.md
+++ b/AgentGuidelines/Guidelines/Architecture/Redux.md
@@ -216,7 +216,7 @@ Do not put SwiftUI types, colors, images, localized display strings, or render-r
Put focused external-boundary abstractions in `Services/`. Services wrap APIs, persistence, packages, frameworks, sensors, system features, and other impure operations. Keep this folder flat while a capability has only one file; introduce a familiar capability folder such as `Services/FaceService/` or `Services/CalibrationService/` when that capability genuinely requires several related files. Middleware calls services; views and reducers do not.
-Prefer a protocol or otherwise injectable contract when a service must be replaced in tests. Keep transport-specific details behind the service boundary.
+Prefer a protocol or otherwise injectable contract when a service must be replaced in tests. Follow [Networking](../Networking.md) for networking implementation, transport ownership, and validation.
Keep a supporting delegate, adapter, or helper beside its service when only that capability uses it. Local ownership is clearer than promoting a service-private framework bridge to a global `Tools/` folder.
diff --git a/AgentGuidelines/Guidelines/CICD.md b/AgentGuidelines/Guidelines/CICD.md
index 5138aca..c96e469 100644
--- a/AgentGuidelines/Guidelines/CICD.md
+++ b/AgentGuidelines/Guidelines/CICD.md
@@ -2,7 +2,7 @@
## Workflow principles
-- Keep CI deterministic, reproducible, and aligned with the repository's supported Xcode, Swift, and platform versions.
+- Keep CI deterministic and reproducible through declared inputs, compiler settings, and validation, using the [runner toolchain policy](#runner-toolchain).
- Treat warnings introduced by a change as failures even when the compiler does not.
- Prefer the smallest permissions required by each workflow and job.
- For a new workflow, use the latest stable major version of every GitHub Action available at the time of creation.
@@ -12,6 +12,26 @@
- Do not place secrets in workflow files, logs, fixtures, or command arguments that may be echoed.
- Keep release workflows separate from pull-request validation when their permissions differ.
+## Runner toolchain
+
+Use the active Xcode and Swift toolchain supplied by the self-hosted runner. Log the selected developer directory, Xcode version/build, and Swift version so failures identify the actual environment. Let dependency resolution, compilation, tests, and required validation expose real incompatibilities after an update; a different version string alone must not fail a job.
+
+Do not pin an exact Xcode release, build number, or bundled Swift compiler version by default. This applies to workflow conditions, equality or text checks, setup-action inputs, versioned installation paths, runner labels, and scripts invoked by CI. Do not replace an exact check with an allowlist or upper bound that still rejects a compatible newer toolchain. Preserve legitimate minimum tools versions, Swift language modes, SDK/deployment requirements, simulator destinations, and capability or first-launch checks. These express supported capabilities rather than the last environment an agent happened to validate.
+
+A version pin is permitted only for a concrete repository-specific reason documented in that repository's `AGENTS.md` or linked durable build/CI documentation. Record the affected workflows and scripts, exact constraint, demonstrated incompatibility or external requirement, evidence, and the condition for revisiting or removing it. A historical upgrade target or a generic claim of reproducibility is not sufficient justification. Keep the exception as narrow as the demonstrated requirement, and report it during the completion audit.
+
+Respect the runner's configured selection, including an inherited `DEVELOPER_DIR`. A process-scoped override for an explicitly requested toolchain investigation or upgrade is appropriate; it does not authorize adding a permanent CI pin or changing machine-global `xcode-select`. Record historical validation versions as evidence without turning them into future acceptance conditions.
+
+For example, a workflow can report its environment without comparing version strings:
+
+```yaml
+- name: Log active toolchain
+ run: |
+ xcode-select -p
+ xcodebuild -version
+ xcrun swiftc --version
+```
+
## Tooling and automation
Fastlane is forbidden in every ThatFactory project and has no exception path. Build repository-owned CI/CD and delivery automation with focused ThatFactory tooling such as `xcode-cloud-mcp` and `app-store-connect-mcp`, plus Swift scripts where repository-specific orchestration is needed.
diff --git a/AgentGuidelines/Guidelines/Development.md b/AgentGuidelines/Guidelines/Development.md
index 0c61a9f..38f650f 100644
--- a/AgentGuidelines/Guidelines/Development.md
+++ b/AgentGuidelines/Guidelines/Development.md
@@ -10,7 +10,7 @@ ThatFactory applications, games, and reusable packages are first-party by defaul
Do not add a third-party dependency merely to save implementation time, reduce code volume, or avoid learning a platform API. Do not make an external dependency acceptable by hiding it behind a first-party wrapper.
-An exception requires explicit approval from the repository owner for the specific dependency and use before changing the dependency graph. If approved, record the decision in durable repository documentation in the same change, such as the architecture document or an ADR. Record the dependency and source, purpose and target scope, why a native or first-party implementation is not appropriate, relevant license, security, and maintenance considerations, version or update policy when material, and the approval context. Do not infer approval from an execution plan, pull-request description, agent choice, or transient chat that merely mentions or uses the dependency. Regardless of where explicit approval occurs, reflect the exception in durable repository documentation.
+Unless these guidelines explicitly pre-approve the dependency for that role, an exception requires explicit approval from the repository owner for the specific dependency and use before changing the dependency graph. If approved, record the decision in durable repository documentation in the same change, such as the architecture document or an ADR. Record the dependency and source, purpose and target scope, why a native or first-party implementation is not appropriate, relevant license, security, and maintenance considerations, version or update policy when material, and the approval context. Do not infer approval from an execution plan, pull-request description, agent choice, or transient chat that merely mentions or uses the dependency. Regardless of where explicit approval occurs, reflect the exception in durable repository documentation.
An existing approved dependency does not authorize a different dependency. Expanding an existing third-party dependency to a new target or runtime role requires the same approval and documentation. Routine version updates that do not change the approved role remain governed by the intentional consumer-update workflow in [Packages](Packages.md).
@@ -18,6 +18,8 @@ For this policy, a third-party dependency is externally maintained source or bin
Tooling dependencies explicitly required by these shared guidelines, such as documentation or build plugins used only by tooling, are pre-approved for that documented role. They must not be linked into or shipped with product runtime targets unless the repository owner separately approves and documents that use.
+For networking, follow [Networking](Networking.md), including its narrow [standing dependency approval](Networking.md#standing-dependency-approval) and capability-gap requirements. That approval does not make every Apple-maintained package a platform dependency.
+
CocoaPods and Carthage are forbidden in every ThatFactory project and are not eligible for the exception process above. Use Swift Package Manager for package dependencies.
## Guidelines version
@@ -37,6 +39,8 @@ Keep each subtree update in its own commit. In the pull-request description, sta
## Completion audit
+For runtime UI verification, follow [Device Hub, physical devices, and simulators](Xcode/DeviceInteraction.md) together with the consumer's local environment constraints. Plan the observable outcome and cleanup before starting a session.
+
Before claiming implementation is complete, handing work to the user, preparing, opening, or updating a pull request, declaring merge readiness, or preparing a release, invoke `$agent-guidelines-audit`.
If the skill is not discoverable in a subtree consumer, read and follow its [SKILL.md](../.agents/skills/agent-guidelines-audit/SKILL.md) directly. The audit is a final verification gate, not a substitute for reading and applying the relevant guidelines during implementation. Resolve in-scope findings and rerun affected checks before handoff. Do not broaden the requested scope merely to satisfy the audit.
diff --git a/AgentGuidelines/Guidelines/GitHub/PullRequests.md b/AgentGuidelines/Guidelines/GitHub/PullRequests.md
index 48b85df..60f4309 100644
--- a/AgentGuidelines/Guidelines/GitHub/PullRequests.md
+++ b/AgentGuidelines/Guidelines/GitHub/PullRequests.md
@@ -1,184 +1,86 @@
# GitHub Pull Requests
-Use this guide whenever creating, reviewing, updating, or merging a GitHub pull request.
+Use this guide whenever creating, reviewing, updating, or merging a GitHub pull request. The self-contained root contracts come from [the canonical review policy](../../ReviewPolicy/Policy.md); [review-policy integration](../../ReviewPolicy/README.md) describes both adoption profiles and freshness checks.
## Before opening
-- Review the complete diff and exclude unrelated changes.
-- Keep each pull request to a coherent review unit with a bounded set of invariants. Split changes that combine independent architecture, persistence, security, transport, and CI concerns when they can be reviewed and delivered separately; do not split merely to minimize line count.
-- State the supported use cases, explicit acceptance criteria, and relevant threat model for behavior whose review priority depends on those boundaries.
-- For security guarantees based on enumerating formats or signatures, define the finite coverage contract and residual risk, or use a systemic boundary that enforces the guarantee without exhaustive enumeration.
-- Follow the repository's pull-request template and local contribution instructions.
-- Run the relevant local validation and document anything that could not be run.
-- Open the pull request without auto-merge and keep it unmerged while automated or agent review is pending. Use draft state only when configured reviewers also run on drafts.
-- When automatic Codex review is enabled, opening the pull request schedules the review. Do not also post `@codex review` or make another manual request; duplicate reviews waste review capacity and tokens. Do not request a Codex review manually unless the user explicitly asks for one.
+- Review the complete diff, keep one coherent review unit, and exclude unrelated changes. State supported use cases, acceptance criteria, threat-model boundaries, validation, and limitations in the PR description.
+- Run relevant local validation and follow the repository's contribution instructions. Open a ready-for-review PR at a stable head without auto-merge. Drafts are appropriate for incomplete preparation, data approval, and source promotion; mark ready before waiting for automatic Codex review.
+- Configure automatic review for all PR authors on opening a ready PR or marking ready, disable exhaustive review, and keep separate Security Review manual. Record actual repository configuration separately from the generic template; this template does not establish that automatic review is configured.
+- One automatic full review is the initial review. Do not post a duplicate manual request, toggle draft/ready to force another round, or casually mention the bot. A mention can start extra cloud work. Manual review and Security Review require explicit owner instruction.
## Consumer subtree review scope
-When reviewing a consumer pull request, do not review or comment on files under `AgentGuidelines/**` after exact tagged-tree provenance has been verified. The subtree is a tracked, synchronized copy marked `linguist-generated`; substantive guideline changes are reviewed in the central `thatfactory/agent-guidelines` pull request. Verify `AgentGuidelines/VERSION`, compare the subtree tree with the matching central tag (for example with `git subtree split --prefix=AgentGuidelines HEAD` and a tree comparison after fetching that tag), and verify the required `.gitattributes` rule. If provenance does not match exactly, review the subtree contents and stop the merge. Report substantive guideline feedback against the central pull request instead.
+After exact tagged-tree provenance has been verified, do not substantively review `AgentGuidelines/**` in a consumer PR. Verify `AgentGuidelines/VERSION`, compare `git rev-parse HEAD:AgentGuidelines` with the matching central tag's root tree, and verify `.gitattributes` contains `AgentGuidelines/** linguist-generated`. A tree-object comparison avoids reconstructing subtree history. If provenance differs, review the discrepancy and stop merge. Substantive shared-policy feedback belongs in the central PR. Review-only consumers have no subtree to exclude.
## Review objective
-Automated review identifies release-blocking regressions; it does not attempt to eliminate every possible improvement.
+Report only substantiated P0/P1 regressions introduced or materially exposed by the change. P0 is a critical security failure, catastrophic durable data loss, or critical outage. P1 requires serious, concrete impact in a supported workflow or documented threat boundary. An acceptance-criterion violation alone does not establish P1. Omit unsolicited P2/P3 hardening, style, optional tests, speculative refactoring, and theoretical completeness. Group one root cause into one finding and report blockers together.
-Classify findings by impact and reachable scope:
+## Review evidence and gate
-- **P0 — critical:** an actively exploitable critical security issue, catastrophic durable data loss, or critical production outage.
-- **P1 — blocking:** a supported use case, explicit acceptance criterion, or documented threat-model boundary has a concrete reachable failure path that causes a security-boundary bypass, durable data loss or corruption, a crash or deadlock, loss of availability, or a serious compatibility regression.
-- **P2 — non-blocking:** robustness, defense-in-depth, bounded edge cases, malformed state that trusted code cannot produce, unsupported scenarios, theoretical completeness, or useful hardening.
-- **P3 — non-blocking:** style, naming, preferred refactoring, documentation polish, or optional test improvements.
-
-Only unresolved P0 and P1 findings block merge. A finding may be technically correct without being release-blocking.
-
-## Review gate
-
-Opening a pull request starts review; it does not authorize merging it.
-
-1. Wait for the configured Codex review to finish. No review yet means pending, not approved.
-2. Record the reviewed head SHA and inspect all review summaries, inline threads, checks, and requested changes.
-3. Assess each comment for technical correctness, severity, supported reachability, and root cause.
-4. Give every thread one explicit disposition: `BLOCKER-P0`, `BLOCKER-P1`, `DEFER-P2`, `DEFER-P3`, `DECLINE`, or `DUPLICATE`.
-5. Batch accepted P0/P1 corrections into one remediation pass and add regression coverage where reasonably possible. Lower-severity improvements may be included when they are small and clearly in scope, but they do not keep the review loop open.
-6. Reply in the original thread with the disposition and either what changed or the concise technical reason for deferring, declining, or grouping it.
-7. Resolve a thread only after its disposition is recorded. Reference a follow-up issue for deferred work when its value justifies one.
-8. Rerun affected validation, then update the pull-request description so it matches the current implementation, validation, deferred work, and remaining limitations.
-9. Recheck the pull request immediately before merge for late P0/P1 findings and check-state changes.
-
-When replying with a commit reference, write the commit hash as raw text without backticks (for example, the hash 185c04f should remain 185c04f). GitHub then auto-links the hash to the commit.
-
-A thumbs-up or clean Codex review satisfies the agent-review step, but it does not replace any human approval required by the repository. Do not enable auto-merge before all review gates are satisfied.
-
-### Codex review state and round budget
-
-This round budget applies only to Codex GitHub reviews: the configured automatic Codex review and any manual `@codex review` request. It does not apply to ChatGPT review or reasoning delegated through Reasoning Relay. An otherwise-authorized Reasoning Relay workflow may request as many Relay review or follow-up delegations as its own governing workflow requires; those requests neither consume this Codex budget nor require repository-owner authorization under it. Do not block an agentic goal waiting for a Codex-budget exception before issuing an otherwise-authorized Reasoning Relay request.
-
-Track enough Codex-review state to prevent duplicate requests and unbounded Codex review loops:
+Track configuration and execution separately in the active task, without adding runtime journals to the repository:
```text
-codex_initial_review_sha
-codex_last_reviewed_sha
-codex_review_requested_sha
-codex_review_round
-codex_pending_review
-codex_unresolved_p0
-codex_unresolved_p1
-codex_deferred_findings
+codex_review_configuration = enabled | disabled | unknown
+codex_review_configuration_evidence =
@@ -25,8 +25,6 @@ For example, a repository using all supported badge configurations could use:
-
-
@@ -42,16 +40,15 @@ Use only badges that describe the repository, in this order:
5. Relevant agent or tooling badges, such as Xcode MCP, Codex, or Claude.
6. DocC, documentation.
7. License.
-8. Updated date.
-9. Revision or latest release.
-10. CI badges.
-11. Release/publishing status when applicable.
+8. CI badges.
+9. Release/publishing workflow status when applicable.
-The common package baseline is Swift, Xcode, Platforms, License, and CI. Add optional badges only when they convey useful repository-specific information. Keep the order stable even when some positions are omitted.
+The common package baseline is Swift, Xcode, Platforms, License, and CI, plus a Release/publishing workflow-status badge when the package has that workflow. Add optional badges only when they convey useful repository-specific information. Keep the order stable even when some positions are omitted.
+
+Swift package READMEs omit Updated/last-commit-date and Revision/latest-release-version badges by default. Add or retain one only when the repository's `AGENTS.md` or linked durable documentation records the specific badge, its source, and the reader need that justifies the exception. A publishing workflow's success/failure badge remains part of the normal convention; it reports operational status rather than a revision or release version. An approved date/version badge belongs after License and before CI, uses a dynamic source, and must not require manual version/date edits.
- Point CI, publishing, and documentation badges at workflows in the current repository; never copy another repository's badge URL unchanged.
- Use descriptive `alt` text. Preserve a repository's established Xcode badge convention when the label intentionally records the last verified Xcode version.
-- Prefer dynamic Updated and Revision badges backed by repository history or releases so maintainers do not edit dates and versions by hand.
- Do not advertise a platform, integration, package manager, or agent that the repository does not support.
- Keep the repository's license in a root `LICENSE` file when reuse or redistribution is permitted.
- Retain the README license badge when the standard badge set applies, but do not add a dedicated License heading or license-description section to a package README. GitHub already presents the repository license beside the README, and the badge provides the summary without duplicating license prose.
@@ -62,7 +59,7 @@ The common package baseline is Swift, Xcode, Platforms, License, and CI. Add opt
- Keep a reusable package focused on one coherent capability.
- Prefer UI-agnostic domain APIs unless UI is the package's explicit purpose.
- Do not add application Redux, navigation, persistence, or product policy to a generic package.
-- A first-party package must not introduce or conceal a third-party runtime dependency. Follow the [external dependency policy](Development.md#external-dependencies) before changing the dependency graph.
+- A first-party package must not introduce or conceal a third-party runtime dependency outside an explicitly approved role. Follow the [external dependency policy](Development.md#external-dependencies) before changing the dependency graph and [Networking](Networking.md) for network implementation and its standing approval.
- Keep public APIs minimal and stable. Prefer composing focused types over introducing umbrella abstractions before multiple consumers need them.
- Declare platform and Swift toolchain requirements explicitly in `Package.swift`.
- New Swift packages must start on the latest supported Swift language and toolchain version. Before adding a major package capability to an older package, plan and complete the required Swift/toolchain modernization first.
@@ -114,6 +111,10 @@ Accept a deviation only when the nearest applicable `AGENTS.md`, or durable docu
Packages own any diagnostics emitted by their implementation. Follow the shared [logging guide](Logging.md) for AppLogger usage, subsystem identity, package emoji prefixes, domain-owned categories, concise messages, privacy, and test coverage. A consuming application must not reproduce package-internal logs.
+Before assigning or changing a package's canonical emoji, inspect the package list on the current `main` branch of the [ThatFactory Swift Package Collection](https://github.com/thatfactory/swift-package-collection) and confirm that no other package uses it. Each package emoji must be unique across ThatFactory so a log prefix identifies one package unambiguously. Treat visually identical emoji spellings that differ only by presentation selectors as the same emoji; do not use an encoding variation to create an apparent distinction.
+
+Declare the selected emoji in the package's local instructions or documentation, use that exact emoji in its package-local logging gateway, and add or update the matching Swift Package Collection entry as part of the package's publication work. An existing collision, a missing registry entry for a published package, or disagreement among the registry, documentation, and emitted prefix blocks release readiness until reconciled.
+
## Development workflow
1. Read the package's local `AGENTS.md`, README, DocC, and public API before changing behavior.
diff --git a/AgentGuidelines/Guidelines/Swift/SwiftUI.md b/AgentGuidelines/Guidelines/Swift/SwiftUI.md
index 82b7cbb..1c01cbf 100644
--- a/AgentGuidelines/Guidelines/Swift/SwiftUI.md
+++ b/AgentGuidelines/Guidelines/Swift/SwiftUI.md
@@ -43,6 +43,13 @@ With SDKs where `@State` is a macro, do not give a state property a declaration
- Avoid unstable environment defaults and freshly created closures that invalidate large subtrees.
- Do not hide unstable values behind fake `Equatable` implementations.
+## Scrolling
+
+- Apply `.scrollBounceBehavior(.basedOnSize)` to new or changed `ScrollView` instances on supported deployment targets, especially inside modally presented sheets. Content that fits should stay still; content that exceeds the viewport can still scroll and bounce.
+- Match the modifier's `axes` to the scroll view. The default affects only the vertical axis, so specify `.horizontal` for horizontal scrolling and both axes when needed.
+- Keep the modifier on the intended scroll view or its narrowest suitable container. The setting propagates through the environment to descendant scrollable views, so check nested scrolling before applying it to a broader hierarchy.
+- Preserve a different bounce behavior only when the supported interaction requires it, and record that reason in consumer guidance. Check Apple API availability for the consumer's deployment targets before applying the modifier.
+
## Modern APIs and scope
- Do not introduce APIs that current Xcode documentation identifies as deprecated or soft-deprecated.
@@ -50,6 +57,86 @@ With SDKs where `@State` is a macro, do not give a state property a declaration
- For SDK-sensitive features, search current Apple documentation through Xcode rather than relying on remembered signatures.
- Apply the current Xcode SwiftUI skill when a new SDK changes source behavior, builder resolution, state initialization, or modifier availability.
+## Native components and presentation
+
+- Prefer native SwiftUI or platform controls and presentation APIs whenever they express the supported interaction. Evaluate sheets, alerts, confirmation dialogs, navigation, menus, pickers, popovers, and similar components before implementing an equivalent. Consult official Apple/Xcode documentation for behavior and availability on the current deployment target, following [documentation lookup](../Xcode/MCP.md#documentation-lookup).
+- Keep branded content and styling inside native components. Custom fonts, button styles, and content inside a native sheet are compatible with this policy when the system retains presentation and dismissal ownership.
+- Do not substitute a sheet-shaped `ZStack`, offset animation, or custom scrim for a suitable native sheet API. The same rule applies to other simulated system components, including custom discard dialogs. Pixel fidelity to a static design and preserving mounted state are insufficient reasons to replace native presentation behavior; a mockup is not approval for an exception.
+- Use a custom equivalent only for an actual native capability gap verified against the supported platform and deployment target. Before implementation, obtain explicit repository-owner approval and record a durable exception in consumer documentation: the required interaction, evaluated native alternatives, concrete missing capability and documentation or reproducible evidence, approved scope, lifecycle ownership, compensating validation, and revisit condition. Do not invent a capability gap or infer approval from existing custom code. An unapproved or undocumented replacement blocks completion.
+
+### System control placement
+
+- Let Apple determine the platform-appropriate placement and behavior of standard navigation, dismissal, confirmation, and window controls. Use native containers and controls for Back, Close, Cancel, Done, and similar actions; preserve the system's adaptation to platform, OS version, available space, and layout direction. Do not impose a universal left/right rule.
+- Express an action's actual intent with supported semantic toolbar placements and button roles, letting the system resolve their position. For example, use `.cancellationAction` for cancellation and `.confirmationAction` for confirmation when those semantics apply. Do not choose a role merely to obtain a desired side, treat every Close action as Cancel, or replace an appropriate semantic placement with `.automatic` merely for its current visual result. Check current Apple documentation and API availability for the target.
+- Preserve native Back navigation and its supported gestures, accessibility behavior, and keyboard or remote interactions. Do not hide and recreate Back, relocate system picker/editor controls, or add a competing close control solely to match another screen or a mockup.
+- Treat apparent placement inconsistencies as an ownership question first: identify whether Apple or app-authored layout controls the position. Keep valid system-selected differences. For app-authored headers or toolbars, remove deliberate placement overrides where a native semantic equivalent supports the interaction. A custom equivalent remains subject to the capability-gap, owner-approval, and durable-exception requirements above; existing custom code is not an exception.
+- Keep app-specific content actions within their intended scope; ordinary custom content layout does not itself replace native system behavior or require a capability-gap exception. An app-authored Close button is not automatically system-owned: determine its action semantics and whether it replaces a supported native control. For standard controls, explicit placement APIs can express a documented platform requirement when semantic APIs do not cover it; record the Apple guidance and target-specific reason. This does not permit overriding system-owned controls for visual uniformity. Align design artifacts with the supported native behavior rather than treating fixed mockup coordinates as authoritative.
+
+Consult Apple's [toolbar design guidance](https://developer.apple.com/design/human-interface-guidelines/toolbars) and [toolbar placement semantics](https://developer.apple.com/documentation/swiftui/toolbaritemplacement) for current platform behavior. Apply the same ownership principle to UIKit/AppKit navigation bars, toolbars, and window chrome.
+
+### Presentation ownership
+
+- Present from the active hierarchy. When a child presentation launches a system picker or editor, attach that presentation to the active child hierarchy rather than an obscured ancestor or unrelated host.
+- Give each child independent dismissal. Read the dismissal action in the child's presentation environment or use its own presentation binding; do not route a child close button or downward dismissal gesture to the parent editor. Keep parent-owned draft state alive across child presentation and dismissal without committing or discarding it implicitly.
+- Make cancellation idempotent across explicit cancel, interactive dismissal, parent dismissal, and asynchronous callbacks. Cancel owned work and reject stale completions after dismissal or replacement so an old result cannot mutate a retained draft or a later presentation.
+- Perform cleanup that depends on completed dismissal through the presentation's dismissal-completion callback, such as `onDismiss`, rather than treating a dismiss request, animation delay, or arbitrary disappearance as proof of completion. Coordinate cleanup with cancellation so repeated callbacks cannot clear parent state or a newer child session.
+
+### Required interaction evidence
+
+For changed native presentations and approved custom equivalents, exercise the supported lifecycle on a simulator or device using [runtime interaction and reporting](../Xcode/MCP.md#build-run-and-interaction). Record the platform, scenario, action, observed outcome, and relevant hierarchy or visual evidence:
+
+- Verify presentation and dismissal animation/dimming, supported interactive dismissal and gesture routing, and parent survival with draft retention. If interactive dismissal is intentionally disabled, verify the restriction and the explicit exit path. Exercise reopening and repeated cancellation.
+- Launch and dismiss any nested system picker or editor from the active child; confirm the expected presentation remains active after each exit.
+- Inspect safe areas, controls and shadow clipping, keyboard/focus restoration, and relevant Dynamic Type and localization layouts during the flow.
+- Exercise asynchronous cancellation and stale completion after dismissal or replacement when work can outlive the presentation; use deterministic tests where they improve coverage of these races alongside runtime interaction.
+
+A static screenshot or a no-op automation call is not evidence that gestures work. Require an actual gesture and its observed result, or recorded manual verification when automation cannot exercise it. Missing relevant runtime evidence blocks completion; report the exact unverified behavior instead of claiming the lifecycle passed.
+
+Use these decisions when auditing an implementation:
+
+| Decision | Audit outcome |
+| --- | --- |
+| Simulated sheet with a suitable native API and no approved durable exception | Blocked |
+| Native nested sheet with branded content, correct ownership, and required interaction evidence | Accepted |
+| Custom equivalent for a verified capability gap with owner approval, durable exception, and compensating evidence | Accepted within the approved scope |
+| Presentation with missing relevant runtime evidence | Blocked |
+
+## Animation
+
+- Use native SwiftUI animation to make apps fluid rather than static. Apply it purposefully to buttons, transitions, interactions, selection, colors, and other visible state changes that benefit from feedback; do not animate every update or add motion for its own sake.
+- Prefer the default SwiftUI animation, using `withAnimation { ... }` or `.animation(.default, value: ...)`, unless the task prompt explicitly requests a specific animation. Prefer system-provided transitions and SF Symbol effects when they fit the interaction instead of recreating them with custom timing, curves, or rendering.
+- Reusable custom-styled controls own their basic visual transitions. Animate enabled/disabled appearance smoothly by default in both directions, without screen-level opt-in. A native `Button` preserves interaction semantics, but does not define transitions for every custom foreground, background, or shadow. Preserve system-owned feedback instead of layering duplicate animation over it.
+- Change enabled state, hit-testing, accessibility state, and action availability immediately. Animate appearance; never delay functional state until an animation finishes. Immediate press, focus, or selection feedback remains appropriate when it improves responsiveness; record an intentional immediate transition and its reason.
+- Preserve stable view identity when only appearance changes. Prefer changing fill, opacity, or shadow values over replacing equivalent view branches.
+- Scope animation to the intended state and visual attributes. Preserve responsive controls, stable layout, and uninterrupted user interaction; animating surrounding layout must not accidentally animate every control inside it. The presence of `.animation` does not prove correct scope: value-triggered animation can affect other changes in the same transaction. Use narrower modifier or closure scope where necessary and supported by the deployment target.
+- Apply the [Reduce Motion policy](#reduce-motion) alongside these animation defaults, including in reusable custom-styled controls.
+
+Consult Apple's [Explore SwiftUI animation](https://developer.apple.com/videos/play/wwdc2023/10156/) for transaction propagation and scoped animation behavior. The reusable-control defaults above are repository policy.
+
+### Reduce Motion
+
+Follow Apple's [Reduced Motion evaluation criteria](https://developer.apple.com/help/app-store-connect/manage-app-accessibility/reduced-motion-evaluation-criteria/) and [motion design guidance](https://developer.apple.com/design/human-interface-guidelines/motion). Evaluate individual animations; do not disable all animation indiscriminately.
+
+- Respect the user's reduced-motion preference as part of normal implementation; no separate task request is required. Preserve native accessibility adaptations and verify custom styling and surrounding animations do not defeat them.
+- Use SwiftUI's [accessibilityReduceMotion](https://developer.apple.com/documentation/swiftui/environmentvalues/accessibilityreducemotion) environment value when app-authored motion needs adaptation. Follow preference changes during use. System preference integration is the repository default; document any equivalent or more granular in-app alternative and verify it meets Apple's criteria rather than requiring a redundant setting.
+- Identify potentially problematic scaling, spinning, peripheral motion, depth simulation (including parallax or animated blur), and multi-axis or multi-speed movement. Remove decorative triggers or replace them with lower-motion feedback when reduced motion is requested. For ongoing motion such as an auto-advancing carousel, stop it or provide a discoverable stop control.
+- Preserve information and usability: replace meaningful motion with suitable alternatives such as a dissolve, highlight fade, or color change. Retain harmless feedback, immediate functional state, and system-owned behavior. A reduced-motion preference does not justify losing status, navigation context, or action availability.
+- Exercise affected flows with the preference on and off, including changing it while the app is running. Record the platform/OS, app revision, actions, outcomes, and limitations. Test custom and native behavior rather than assuming an environment read or native control proves support.
+
+#### Declaring support
+
+Claim Reduced Motion support only after evaluating all common tasks for the platform being declared against Apple's criteria. Follow Apple's [Accessibility Nutrition Labels guidance](https://developer.apple.com/help/app-store-connect/manage-app-accessibility/overview-of-accessibility-nutrition-labels) for task coverage, required third-party or user-generated content, and advertising. Record the evaluated tasks, evidence, remaining limitations, and declaration scope in consumer documentation. An app with no problematic motion can qualify; a guideline update or a single compliant component cannot establish app-wide support. Re-evaluate support with each app update, and withhold or correct a claim when relevant evidence is missing or a regression invalidates it. Updating App Store Connect remains a separately scoped metadata operation under [App Store metadata](../AppStore.md).
+
+## Image rendering
+
+- Use retained, display-appropriate derivatives for large dynamic images in small, frequently updated views instead of repeatedly rendering the original bitmap. This applies to photos, downloaded images, generated images, and other bitmap sources; an expensive rendering path does not by itself establish a provider defect.
+- Account for display scale, aspect-fit/fill requirements, orientation, fidelity, and bounded intermediate/cache memory. Refresh derivatives when their source or relevant presentation requirements change.
+- Keep expensive loading, decoding, resizing, and conversion outside view construction and repeated interaction paths. Perform expensive preparation off the main actor when supported and concurrency-safe; do not prescribe detached tasks as a universal solution.
+- Reject stale asynchronous results after replacement, cancellation, or removal. Keep presentation derivatives separate from authoritative originals needed for editing, saving, or export.
+- Inspect the representation actually drawn. A small display frame does not establish a small decoded image, and caching a `UIImage` alone does not remove rendering cost. Choose preparation based on measured cost and required fidelity; do not impose blanket bans on `Image`, `UIImage(data:)`, or full-resolution presentation, or universal pixel sizes, color formats, cache architectures, or `drawingGroup()` requirements.
+
+Apple's [iOS Memory Deep Dive](https://developer.apple.com/videos/play/wwdc2018/416/) explains image memory costs and demonstrates ImageIO downsampling for thumbnails without first decoding the full image. Use the [animation and image-rendering audit](../../.agents/skills/agent-guidelines-audit/SKILL.md#audit-animation-and-image-rendering) to verify affected interactions and record performance evidence.
+
## Previews
- Put previews at the end of the file under `// MARK: - Preview`.
diff --git a/AgentGuidelines/Guidelines/Testing/UnitTesting.md b/AgentGuidelines/Guidelines/Testing/UnitTesting.md
index a694331..cc14fb3 100644
--- a/AgentGuidelines/Guidelines/Testing/UnitTesting.md
+++ b/AgentGuidelines/Guidelines/Testing/UnitTesting.md
@@ -50,3 +50,5 @@
- Report which tests ran and whether any relevant tests could not be executed.
Follow [Xcode MCP](../Xcode/MCP.md) for build and runtime verification.
+
+Follow [Networking](../Networking.md#ownership-and-validation) for networking test boundaries and required evidence.
diff --git a/AgentGuidelines/Guidelines/Xcode/DeviceInteraction.md b/AgentGuidelines/Guidelines/Xcode/DeviceInteraction.md
new file mode 100644
index 0000000..da9267c
--- /dev/null
+++ b/AgentGuidelines/Guidelines/Xcode/DeviceInteraction.md
@@ -0,0 +1,109 @@
+# Device Hub, Physical Devices, and Simulators
+
+Use this guide when verifying an Apple-platform interface or investigating runtime behavior. Follow [Xcode MCP](MCP.md) for tool priority and documentation lookup. A successful build proves compilation; it does not prove that taps, focus, keyboard transitions, presentation, or cancellation work.
+
+## Select the environment
+
+1. Read the consumer's nearest `AGENTS.md` for its designated simulator, account, signing, CI, resource, and accessibility-testing constraints. Reuse that environment; do not create, erase, or boot extra simulators merely for convenience.
+2. Use a physical device only when the owner explicitly requests physical-device interaction for the current task. A request for an iPhone-sized interface or visual verification does not imply permission to use a paired personal device. Existing task authorization remains valid; do not ask again for each ordinary test action.
+3. Verify that the feature is available on the selected runtime and hardware using current Apple documentation and the framework's availability API. Simulator support varies: a fallback screen or unavailable Apple Intelligence feature does not verify the real native feature. Report that limitation and obtain physical-device authorization if needed.
+4. Record the app revision/build, scheme, configuration, Xcode/SDK versions, device model, OS, locale, and relevant input settings. Resolve the exact destination identifier locally; do not publish personal device names, serial numbers, or identifiers in shared documentation.
+5. Assign one operator to the interactive session. Concurrent agents must not tap, launch, install, or change settings on the same device. Coordinate builds and simulator use with CI before starting.
+
+Apple describes simulator limitations and run destinations in [Running your app on simulated or physical devices](https://developer.apple.com/documentation/xcode/running-your-app-on-simulated-or-physical-devices). Simulator success is not physical-device performance or feature evidence.
+
+## Discover tools and skills
+
+Inspect the tools actually exposed by the host before choosing a workflow. Prefer native Xcode MCP operations on the open project; external access uses `xcrun mcpbridge` and requires the user's Xcode permission. Use XcodeBuildMCP when native tooling is unavailable or cannot perform the needed operation. It can provide build, install, launch, and logging support without necessarily providing physical-device touch control.
+
+Read the installed `device-interaction` skill when available. It describes workspace-backed versus already-installed-app sessions, install/run, event synthesis, hierarchy capture, and session cleanup. If that installed skill requires a subagent, give it exclusive session ownership. Read an installed iOS debugger skill for XcodeBuildMCP workflows when relevant; a simulator-oriented skill does not establish physical-device support. Skill and tool names vary by installation: discover their current schemas, and do not call an operation merely because a guide mentions it. Distill policy rather than copying exported skill implementations into the repository.
+
+For native device sessions, prefer a workspace-backed session when building the app and an existing-app session when no build is needed. Use one-run arguments and environment variables instead of editing shared schemes. Capture the hierarchy and screenshot, interact, recapture, then end the session. When a hierarchy provides hit points or application-activation annotations, follow the installed tool's contract. A remote placeholder without children requires visual targeting; it does not prove that the device has no controls.
+
+When the required interaction is unavailable through MCP, use the host's supported computer-use capability to operate Device Hub. Do not invent touch support in a build-only tool or replace a missing physical test with simulator evidence.
+
+## Prepare and run a physical device
+
+Use the owner's already paired, unlocked device when possible. Pairing, trust confirmation, Developer Mode, account sign-in, and passcodes are security prerequisites for the owner to complete when required; do not automate around them or reset trust to repair a test. Select the authorized device in Device Hub and verify its model and OS before installing anything. See Apple's [device management](https://developer.apple.com/documentation/xcode/managing-your-simulated-and-physical-devices-in-device-hub) and [Device Hub access](https://support.apple.com/guide/personal-safety/ips37dbab2a1/web) documentation.
+
+Build for the exact destination with the project's normal development signing, provisioning, bundle identifier, and required entitlements. An unsigned CI build is not an interactive device build. Keep install, launch, and UI verification as separate evidence: installation can succeed while launch fails, and launch can succeed while the intended screen is absent. Preserve the existing app container and user data; uninstalling the user's app or resetting its storage is not a routine troubleshooting step.
+
+If MCP cannot perform an operation, Apple's command-line tools are a fallback. Inspect the installed help first, because options and device support change. These examples use placeholders, not literal device identifiers:
+
+```sh
+xcodebuild -version
+xcrun devicectl list devices
+xcrun devicectl help device install app
+xcrun devicectl help device process launch
+
+xcrun devicectl device install app --device '