field_ios

In-the-field app for Radroots on iOS
git clone https://radroots.dev/git/field_ios.git
Log | Files | Refs | README | LICENSE

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.