The automatic-migration contract
An entry becomes AUTO only when PkgLift can establish all of the following:
- an exact pod or subspec identifier;
- a verified SwiftPM repository and product;
- a stable locked version at or above the mapping’s verified minimum;
- one unambiguous destination Xcode target;
- a complete, non-empty PBX source profile;
- explicit mapping support for every Swift, Objective-C, Objective-C++, C, or C++ consumer language present;
- no detected integration or project shape that requires unsupported execution or unsafe inference.
Missing any one of those facts is enough to stop automatic mutation.
Why exact identifiers matter
A base pod mapping never automatically applies to an undeclared subspec. Product names can differ from pod names, and repositories can publish several products. PkgLift therefore treats exact mapping data as executable evidence—not as a fuzzy recommendation.
Constructs that force review
Dynamic Ruby
Computed dependency or target declarations cannot be proven by a static parser without executing project code.
Install hooks and script phases
Behavior may be coupled to CocoaPods integration in ways that a package substitution cannot safely infer.
External pod sources
Private, path, Git, or custom-source dependencies may not correspond to a public package identity.
Incomplete target profiles
Unknown compiled file types or incomplete PBX metadata prevent PkgLift from proving consumer-language coverage.
Ambiguous targets or workspaces
PkgLift requires explicit selection instead of linking a product to the first plausible target.
Other integration owners
Carthage, React Native, Flutter, and Capacitor markers stop AUTO because another dependency system owns part of the graph.
Clean worktree before mutation
A dirty worktree makes it difficult to distinguish your edits from tool edits and makes rollback unreliable. PkgLift’s apply phase therefore fails before mutation when Git reports changes.
Typed, atomic changes
The saved plan contains typed actions. The migration layer orchestrates project changes through PkgLift’s Xcode module and retains local rollback material. It does not execute an arbitrary text-replacement script across the project.
Verification is part of migration
Structural verification checks expected package, product, and target linkage. Optional build verification resolves packages and invokes xcodebuild with an explicit scheme and separately validated arguments.
A refusal is useful output
REVIEW, BLOCKED, and UNKNOWN identify the exact boundary where evidence ends. They let a maintainer keep a dependency on CocoaPods, investigate manually, add a fixture, or contribute a verified mapping without pretending the entire project can be converted in one pass.