AGENTS.md (10605B)
1 # Tera iOS app agent specification 2 3 This file applies to the complete standalone iOS app repository. A closer 4 `AGENTS.md` overrides it for its subtree. 5 6 ## Authority and repository boundary 7 8 - This capsule owns the public iOS application, its Swift package, generated 9 Xcode project, Apple host lifecycle, app state and views, FFI installation 10 boundary, privacy manifest, public API snapshot, and standalone validation. 11 It also owns application Rust presentation/lifecycle policy and application 12 FFI. The approved successor places reusable domain, command, durable signing, 13 outbox, history and recovery orchestration in the public Lib SDK. Keep one 14 root Rust workspace; 15 application packages belong under `core/crates`. Native artifacts use the 16 owned tera_ffi and tera_bindgen packages with exact shared foundation pins. 17 - `radroots.lib.source-lock.v1.toml`, `Cargo.toml`, and 18 the foundation section of generated `TeraFFI/source.lock` must select the same 19 exact remotely reachable public Lib revision and release version. The lock 20 separately identifies the owned Tera source tree and installed manifest. 21 `Package.swift`, both 22 `Package.resolved` files, and `project.yml` own exact Apple package inputs. 23 - `TeraFFI/provenance.json`, `TeraFFI/api/**`, `api/**`, `release/**`, 24 generated project/source inputs, and the package locks are machine evidence. 25 Do not hand-edit generated bindings, XCFramework contents, provenance, SBOM, 26 project output, or API snapshots. 27 - `TeraFFI/producer.toml` separately governs the owned Tera producer. 28 Stage its declared source inputs before `make ffi-source-write`; check with 29 `make ffi-source-check`. Source records identify a staged input tree and exact 30 build tuple under extbuild output. They do not establish installed artifacts 31 or remote release qualification; installed provenance remains separate. 32 `make ffi-candidate-build ffi-candidate-check` builds and validates the exact 33 owned native artifact bundle in external staging. `make ffi-bootstrap` 34 installs its matching framework, bindings, API and source records with a 35 separate nonempty installed manifest. Local evidence is not release qualification. 36 - Human specifications, decisions, migration history, runbooks, and 37 qualification evidence are parent-owned under `docs/oss/ios_app/**`. They 38 are absent from a standalone clone and must never become a build, test, 39 package, generation, or release input for this capsule. 40 - `docs/**`, `.github/**`, and `.act/**` are forbidden tracked roots. Public 41 commands remain forge agnostic; cross-repository workflow proof belongs only 42 to the parent workspace's root `.act/**` surface. 43 - Do not depend on non-public parent paths, non-public contracts, implicit 44 sibling checkouts, floating branches/tags, or unrecorded local artifacts. 45 46 ## Product and security boundaries 47 48 - The product has exactly two bottom tabs, Today and Add, and retains its five 49 current creation families. Cached Today and local Add must remain usable 50 independently of network readiness. The approved successor is seller-only: 51 offerings, private inquiries/replies, incoming orders, stock and handover 52 consume shared SDK operations. Buyer jobs remain in shared SDK/CLI; do not 53 add shopping, payment, farm hierarchy, CRDT or unrelated transport surfaces. 54 Approval of this target does not claim those seller workflows are implemented 55 or qualified. Preserve their actual source, artifacts and proving inputs. 56 - The Swift host owns Apple presentation, lifecycle callbacks, 57 user-presence prompts, Keychain integration, foreground/background 58 scheduling, and translation between generated SDK DTOs and view state. 59 - Shared validation, business transitions, durable command/issuance receipts, 60 persistence and reusable recovery have one public Rust SDK owner. Reimplement 61 reusable app behavior independently in Lib with provenance, notices and 62 meaningful retained-test mappings; do not relabel app source licensing. 63 Application Rust and Swift own presentation, form editing, local consent, 64 media acquisition, custody and lifecycle adaptation at exact public pins. 65 They must not fork canonical domain policy or own a second authority ledger. 66 Swift must not own a parallel database. 67 - Preserve installed bundle/Keychain identities and frozen signed operation 68 identities. The clean break uses explicit new persistence namespaces with 69 protected export/quarantine and verified nonpublishing recovery. Never 70 silently reset custody, drafts, evidence, obligations or Unknown issuance. 71 - Keep identity secrets in the Apple credential boundary. Never log, snapshot, 72 serialize, fixture, or expose secret material, raw private event content, 73 credentials, tokens, private paths, or unsafe internal errors. 74 - Background work is host-owned, explicit, bounded, cancelable, and recoverable 75 across app lifecycle changes. Do not add hidden workers, process-global 76 runtime ownership, implicit relays, or direct database authority. 77 - Services-hardening generated changes must adopt the approved four coverage 78 states and three outcomes across Swift and FFI together. Do not retain 79 prototype evidence, receipt, outcome, or compatibility aliases. 80 - Physical-device development must use one exact UDID, an explicitly supplied 81 development team, a Debug `iphoneos` build, and verified TLS endpoints. 82 Never select the first device, disable signing or certificate verification, 83 rewrite the checked-in Debug defaults, or treat local-device evidence as 84 approved remote qualification. 85 86 ## Generated and project files 87 88 - Change canonical producer contracts and generators before regenerating FFI 89 or SDK output. Inspect every generated diff and run freshness/API checks. 90 - `scripts/generate-project.sh` owns `Tera.xcodeproj`; edit `project.yml` 91 and canonical source inputs rather than hand-editing generated project data. 92 - `TeraFFI/scripts/verify-installed-artifacts.sh` must reject missing, 93 stale, mismatched, or unproven FFI installations before Swift/Xcode work. 94 - Keep SwiftPM and Xcode workspace resolved revisions synchronized. Never allow 95 automatic dependency updates to select release inputs. 96 - Repository scripts must keep Xcode derived data and source/package caches, 97 SwiftPM scratch/cache output, and Cargo target output under extbuild-owned 98 paths. `TeraFFI/.build/out/**` and `TeraFFI/.radroots/source/**` are 99 ignored, rebuildable repo-local staging/source cache; they are never 100 canonical source, tracked output, or independent release authority. 101 102 ## Working and verification rules 103 104 - Inspect `git status --short`, relevant locks/contracts, package/project 105 manifests, source, tests, scripts, generated artifacts, and snapshots before 106 editing. Preserve unrelated work. 107 - Run `cargo extbuild doctor` before the first mutating build, test, check, 108 dependency, package, generation, or snapshot command, then use the 109 repository's Make/script surfaces, which route work through 110 `cargo extbuild run -- ...`. 111 - `make package-contract-check` is the narrow standalone source-lock, 112 package-lock, privacy, version, and forbidden-root guard. 113 - Persona qualification must use `scripts/persona-verifier.sh`, the exact 114 Python and schema dependency lock under `scripts/persona-verifier/**`, and 115 offline frozen resolution. Populate the exact lock only through 116 `make persona-verifier-bootstrap`; do not bypass it with ambient Python. 117 - `make swift-quality` applies the checked-in SwiftFormat and SwiftLint policy 118 to repository-owned package, app, unit-test, API-test, and UI-test sources; 119 generated bindings and dependency/build output are excluded. It also runs 120 the exact checked SwiftLint debt baseline, locked Ruff checks, and the 121 closed size/complexity ratchet. Do not broaden a legacy exception or add a 122 new exception to admit new code; decompose the new responsibility instead. 123 - `make maintainability-check` is the narrow fail-closed physical-line and 124 Python-AST complexity gate. Its source revision records the pre-ratchet 125 inventory, exception ceilings may only decrease or disappear, and newly 126 bounded modules must remain below the fixed thresholds. 127 - `make linux-shared-rust` runs explicit locked native packages in the pinned 128 Linux x86_64 Rust runner while keeping Cargo caches and output under the 129 extbuild project root. 130 - `make bootstrap` performs networked source/artifact bootstrap. `make verify` 131 is the complete package, Xcode build/test, UI, and API-snapshot lane. Use an 132 explicitly installed simulator name when the default is unavailable. 133 - `make release-evidence-write` regenerates deterministic unsigned release 134 evidence from exact locks and artifacts. `make release-preflight` checks its 135 freshness and source authority without signing, tagging, or publication. 136 - Run the smallest credible target while iterating, followed by the complete 137 affected standalone lane. Never claim a command passed unless it ran 138 successfully; report missing Xcode, simulator, signing, or network 139 prerequisites exactly. 140 - Prefer explicit typed state, deterministic transformations, bounded inputs, 141 narrow side effects, safe errors, and fail-closed validation. Avoid `unsafe` 142 and forced unwraps in production paths unless a local invariant is explicit 143 and tested. 144 145 ## Changes and external gates 146 147 - Make one coherent, reviewable target-state change at a time. Keep source, 148 tests, machine contracts, generated outputs, locks, snapshots, and public 149 README material aligned. 150 - Use focused commit subjects in the repository's established imperative 151 style. 152 - Normative product changes follow their approved task authority and matching 153 standalone machine contracts in the same ordered sequence. Historical 154 services-hardening evidence remains immutable and does not override the 155 approved shared SDK and seller-only target. Do not create a local human 156 deviation ledger. 157 - Do not push, tag, publish packages, deploy, change signing identities, 158 profiles, entitlements, registry ownership, or credentials without separate 159 explicit authority. 160 161 ## Definition of done 162 163 - The requested behavior is complete at the correct Apple-host, generated FFI, 164 package, project, or application boundary. 165 - Relevant package/Xcode/tool validation passed, generated output and locks are 166 fresh, public API snapshots agree, and zero `docs/**`, `.github/**`, or 167 `.act/**` roots exist. 168 - The final review finds no secret exposure, hidden runtime ownership, private 169 dependency, unrelated change, or unreported skipped lane, and records whether 170 the next sequence step is safe.