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