arcane-cli 1.12.2 → 1.12.3

package/README.md

@@ -9,7 +9,7 @@
 
 **Cast spells to ship software** — the methodology layer for AI-assisted development.
 
-AI agents can write your code; Arcane gives them the discipline to *plan it, govern it, test it, review it, and **ship** it.*
+AI agents can write your code; the Arcane framework gives them the discipline to *plan it, govern it, test it, review it, and **ship** it.*
 
 [![npm version](https://img.shields.io/npm/v/arcane-cli?style=flat-square&color=6f9fd8&label=npm)](https://www.npmjs.com/package/arcane-cli)
 [![npm downloads](https://img.shields.io/npm/dm/arcane-cli?style=flat-square&color=6f9fd8)](https://www.npmjs.com/package/arcane-cli)
@@ -30,7 +30,7 @@ npm install -g arcane-cli   #  then:  spell init
 
 <div align="center">
 
-**🔁 opinionated lifecycle** &nbsp;·&nbsp; **📜 <!--count:spells-->41<!--/count:spells--> spells** &nbsp;·&nbsp; **🤖 <!--count:agents-->12<!--/count:agents--> agents** &nbsp;·&nbsp; **⚖️ <!--count:governance-->25<!--/count:governance--> governance standards** &nbsp;·&nbsp; **📝 markdown-native** &nbsp;·&nbsp; **🔌 any AI client / tracker**
+**🔁 opinionated lifecycle** &nbsp;·&nbsp; **📜 <!--count:spells-->41<!--/count:spells--> spells** &nbsp;·&nbsp; **🤖 <!--count:agents-->12<!--/count:agents--> agents** &nbsp;·&nbsp; **⚖️ <!--count:governance-->25<!--/count:governance--> governance standards** &nbsp;·&nbsp; **📝 markdown-native** &nbsp;·&nbsp; **🔌 tested with Claude Code, GitHub Copilot and Codex · GitHub or Azure DevOps**
 
 </div>
 
@@ -87,7 +87,7 @@ AI coding agents are great at *generating code*. They're terrible at *shipping s
 
 Ask one to "build a feature" and you get a pile of plausible code with no plan, no tests you trust, no review, no governance, and no repeatable path from idea to a merged, deployed change. The gap isn't code generation — it's **methodology**.
 
-**Arcane is that missing layer.** It's a structured, opinionated lifecycle — the **Spell Loop** — plus the governance, agent roles, and templates that make AI-driven development reproducible instead of chaotic. You stay in the driver's seat and cast `spell`s; the framework keeps the work on rails.
+**The Arcane framework is that missing layer.** It's a structured, opinionated lifecycle — the **Spell Loop** — plus the governance, agent roles, and templates that make AI-driven development reproducible instead of chaotic. You stay in the driver's seat and cast `spell`s; the framework keeps the work on rails.
 
 ---
 
@@ -109,7 +109,7 @@ Plus session and operational spells — `/spell-open-session`, `/spell-close-ses
 
 ## What's in the box
 
-Arcane isn't a prompt snippet — it's a full framework. Everything installs into your repo as plain, reviewable markdown. Each spell is authored once, in `.arcane/spells/`, and reaches Copilot, Claude Code and Codex through thin generated shims — one source of truth, no per-client copies to drift apart.
+It isn't a prompt snippet — it's a full framework. Everything installs into your repo as plain, reviewable markdown. Each spell is authored once, in `.arcane/spells/`, and reaches Copilot, Claude Code and Codex through thin generated shims — one source of truth, no per-client copies to drift apart.
 
 | Layer | What you get |
 | --- | --- |
@@ -146,6 +146,40 @@ Arcane isn't a prompt snippet — it's a full framework. Everything installs int
 
 ---
 
+## What the framework does
+
+Every line says how it holds, because a rule nobody checks should not read like one that is checked. *CLI:* the `spell` command, or a hook it installs, does it. *Spell step:* your AI client does it when the work runs through the spells. *Convention:* the standards ask for it; nothing checks it.
+
+**The memory lives in your repository.**
+- One command installs your standards into any repository: governance documents, spell prompts and agent definitions, with a manifest that records a hash of every file it placed. *CLI*
+- Every session opens by rebuilding context from the repository and closes by writing a dated journal entry and a handoff the next session reads first. *Spell step*
+- Drift is caught at session open, from decision ids that skip a number to installed files that differ from the framework's copies; high-severity drift stops the session until you decide. *Spell step*
+
+**Your edits survive updates.**
+- A file you edited is three-way merged with the new version, with conflict markers where the two disagree. Leftover files are reported, and removed only when you ask and only when a recorded hash, or for older installs git history, shows them untouched. *CLI*
+- Updates refuse to run over uncommitted changes or outside a git repository. *CLI*
+
+**Done means checked.**
+- At close, every piece of background work is classified succeeded, failed, pending, dispatched or unverifiable; only "succeeded" may be called done. *Spell step*
+- After a merge, the spell checks that each closed issue's change is actually in the merged diff. *Spell step*
+
+**Gates that block, and gates that ask.**
+- No commit without your approval in an interactive session: the spell shows the diff and the message, fingerprints that exact pair, and re-checks it right before committing. *Spell step*
+- Blocked means blocked: a pre-push hook refuses, and every remote's push URL is pointed at a sentinel, so `--no-verify` does not help. A remote added later stays live until you re-apply the block; `spell doctor` names it. *CLI*
+
+**Agents earn trust.**
+- Define your agents once; the CLI writes them where Claude Code, GitHub Copilot and Codex each expect them. *CLI*
+- Six trust levels per agent per repository, from spectator to archmage. From level four an agent may commit and merge on its own; below that, it queues a pull request for a person. *Spell step · Convention*
+- Every agent commit made through the spells names its agent, model, model source and provider in trailers, and the approving person is the committer. *Spell step*
+
+**What it does not do.**
+- It does not run your agents or call an AI model. The spells are instructions your AI client follows; the CLI installs them, keeps them current and checks the repository.
+- It does not intercept raw git. A commit you type by hand skips the spells' approval and test gates.
+- The credential scan looks for known patterns: it can find a leak, never prove a commit is clean.
+- The push controls stop an accidental push, not a determined operator.
+
+---
+
 ## Meet the agents
 
 Twelve legendary agents ship with Arcane — **the Arcanos**. Each is a **role** with a **code name**; within Arcane the two are aliases: summon `Merlin` or summon `the architect` and you get the same agent. Every namesake is public domain — golden-age stage magicians, myth, and classic literature. Run `spell agents init` and choose how they're named — the **Arcanos** roster below, plain **generic** role labels, **random** names, or your own **custom** universe.
@@ -328,7 +362,7 @@ If a repository that opted in ever lands on a machine with no tier, `spell updat
 
 ## Philosophy
 
-- **Opinionated about *how*, pluggable about *which*.** Arcane is strict about the lifecycle, governance, and commit discipline — and adapter-friendly about your tools (any AI client, any tracker, GitHub or Azure DevOps).
+- **Opinionated about *how*, pluggable about *which*.** The framework is strict about the lifecycle, governance, and commit discipline — and adapter-friendly about your tools (tested with Claude Code, GitHub Copilot and Codex; GitHub or Azure DevOps).
 - **Markdown is the source of truth.** Everything is plain, reviewable, version-controlled text. No lock-in, no opaque state.
 - **Reproducible by design.** Spinning up a new project should mean running `spell init`, not redoing months of process work.
 
@@ -336,7 +370,7 @@ If a repository that opted in ever lands on a machine with no tier, `spell updat
 
 ## Built in public
 
-Arcane is built *with Arcane*. From this repo's first commit forward, development happens in the open — planned, implemented, reviewed, and shipped using its own spells, with each session logged. Want to see how the methodology actually works? Watch the commit history.
+The Arcane framework is built *with itself*. From this repo's first commit forward, development happens in the open — planned, implemented, reviewed, and shipped using its own spells, with each session logged. Want to see how the methodology actually works? Watch the commit history.
 
 ---
 
@@ -364,5 +398,5 @@ npm run typecheck:all  # type-check src/, scripts/, test/ and the root configs
 > The *Arcane* name, logo, and agent art are brand assets of Code Magician LLC; the source code is MIT-licensed.
 
 <div align="center">
-<sub>Built by <a href="https://github.com/codemagicianhq">Code Magician</a> · <code>spell</code> your way to shipped.</sub>
+<sub>Built by <a href="https://codemagician.ai">Code Magician</a> · <code>spell</code> your way to shipped.</sub>
 </div>

package/dist/assets/.arcane/governance/mobile-release-standards.md

@@ -13,7 +13,8 @@ Durable facts about how the Apple App Store and Google Play review consoles and
 actually behave — true regardless of which build tool produced the binary. These are platform
 properties, not Expo/EAS-specific tooling behavior; the EAS-specific workflow that consumes these rules
 lives in `spell-eas-store-deploy`. Sourced from two real dogfooding runs (a first-ever App Store
-submission, then a from-zero Google Play listing to a live production release) — every rule here was hit
+submission, then a from-zero Google Play listing to a live production release) and, for the two release
+gates (MR-15, MR-16), a consumer's later store release reported on 2026-10-18 — every rule here was hit
 for real, not derived from documentation alone.
 
 ## Executive Summary
@@ -30,6 +31,10 @@ for real, not derived from documentation alone.
 - Two platform-specific binary/UI constraints (notification icon requirements, a native dialog's button
   cap) have no equivalent on the other platform and are easy to carry over incorrectly from iOS-first
   development.
+- Two release gates hold across releases rather than within one: every store version still on phones
+  keeps an update path (MR-15), and every build machine whose Xcode can change is pinned to one (MR-16).
+  Both failures are silent: older binaries simply stop receiving updates, or a binary built from
+  unchanged code crashes at launch.
 
 ---
 
@@ -51,6 +56,8 @@ for real, not derived from documentation alone.
 | MR-12 | Audit the permissions the built artifact actually declares, not what the source code appears to use. |
 | MR-13 | Android push-notification icons need a dedicated monochrome asset shipped in a native build; there is no OTA path for this. |
 | MR-14 | Android's native `AlertDialog` silently caps at three buttons; a menu built on `Alert.alert` past that cap loses the overflow, typically the dismiss action. |
+| MR-15 | Every store version still in use needs an update path; audit the binary versions still on phones before each store release. |
+| MR-16 | Pin the Xcode on any build machine where it can change between builds; fail the build when another version is active. |
 
 ---
 
@@ -215,6 +222,40 @@ the *Cancel* row, leaving a dialog with no way to dismiss it. iOS has no equival
 
 **Rule (MR-14): For any Android menu that could exceed three options, use a real bottom sheet dismissible at least three ways (an explicit cancel row, a scrim tap, and the hardware back gesture) instead of `Alert.alert`. Enforcement: explicitly advisory prose (ARC-023) — spell-eas-store-deploy's Known Pitfalls list cites this rule for awareness, but the fix is a UI code change with no console or platform state for the deploy workflow to check before proceeding; catching it depends on code review, not this spell.**
 
+---
+
+## Release gates
+
+### MR-15: Every store version still in use needs an update path
+
+A store release does not retire the binaries before it. Phones keep running an older store version for
+weeks or months (automatic updates are off, the device is short of storage, the user ignores the store),
+and nothing in either store moves them. An over-the-air update system delivers a new JavaScript bundle
+only to binaries whose native compatibility version matches the one the update was published for
+(expo-updates calls it the runtime version), and a project that derives that version from the app
+version gives every store version its own. So once a new store version ships, updates published from
+current code reach only the new binary. Every older binary receives nothing new, and nothing reports it:
+not the device, not the store console, not the publish step. A fix shipped as an update never reaches
+those phones, and a breaking server change can leave them failing with no way forward short of the store.
+An inventory taken from the published updates misses exactly the versions at risk: one that never
+received an update leaves no trace there. And the version a release replaces still receives updates
+until the moment the release ships.
+
+**Rule (MR-15): Before each store release, list every binary version still in use, from the store releases, not from the updates published to them, and confirm each has an update path, judging each as it will stand once the release ships. An update path is either updates still published for the version's native compatibility version or an in-app prompt that sends it to the store; a version with phones on it and neither is stranded. Before the release ships, give each stranded version one (a backported update, which can carry the prompt) or record the operator's decision to leave it. Enforcement: structured spell gate (ARC-023) — spell-eas-store-deploy's runtime audit is the first step of every repeat deployment, and the release report names each stranded runtime with the route chosen for it; no executable check reads the audit's result.**
+
+### MR-16: Pin the Xcode wherever it can change between builds
+
+Xcode stamps its toolchain into every iOS binary it builds (`DTXcode` and `DTSDKName` in the app's
+`Info.plist`), and the toolchain is part of what ships: a binary built with an Xcode the project's
+dependencies were not built for can crash at launch while the same JavaScript runs fine as an
+over-the-air update on a binary built earlier. A build service that selects a versioned image for each
+build pins the toolchain with it. A self-hosted build Mac pins nothing unless told to, and neither does a
+hosted CI runner whose default Xcode moves with its image: when the Xcode changes, the next build of an
+unchanged commit uses a different toolchain and no step fails. The crash then looks like a code defect,
+and reading the code first is the slow way to learn that it is not one.
+
+**Rule (MR-16): On any build machine whose Xcode can change between builds (a self-hosted Mac, or a hosted CI runner whose default Xcode moves with its image), pin the Xcode per build (installed side by side and selected with `DEVELOPER_DIR`), fail the build when the pinned toolchain is missing or another version is active, and move the pin only on purpose, never through an automatic update. When a store build crashes at launch but the same code runs elsewhere, compare `DTXcode` and `DTSDKName` of the working and the crashing binary before reading any code. Enforcement: structured spell gate (ARC-023) — spell-eas-store-deploy's toolchain step has the build job carry a guard step that fails the run on a missing or mismatched Xcode, and reads that guard's result in the build's own run before a store build continues; the guard itself is an executable check in the consuming project's own pipeline, and no Arcane tooling verifies that it exists.**
+
 ## Related
 
 - [[.arcane/governance/external-verification-standards|External Verification Standards]] — `EV-01`

package/dist/assets/.arcane/spells/spell-eas-store-deploy.md

@@ -14,10 +14,15 @@ agent: agent
 - Roughly 80% of the material (credentials, `eas.json` profile shape, build-number handling, OTA rules)
   is shared between the two stores; only the store-console work genuinely diverges. Covered once in a
   shared preamble, then two store-specific sections.
-- **Deliberately scoped to EAS Build + EAS Submit** — no local Xcode, Xcode Cloud, or Fastlane coverage.
-  That scope is what keeps every step concrete and copy-pasteable.
-- Every lesson here was hit for real across two dogfooding runs (a first-ever App Store submission, then
-  a from-zero Google Play listing to a live production release) — none is general knowledge restated.
+- **Deliberately scoped to EAS Build, EAS Submit and EAS Update** — no local Xcode, Xcode Cloud, or Fastlane coverage.
+  That scope is what keeps every step concrete and copy-pasteable. The only local toolchain it touches is
+  a build machine running `eas build --local`, and only to pin it (EAS Update lifecycle, part 3).
+- An **EAS Update lifecycle** section covers what a store release leaves behind and what surrounds it: the
+  runtimes older store versions keep running, an in-app store update prompt, toolchain pinning for
+  machines running `eas build --local`, and when to announce a version as the latest.
+- Every lesson here was hit for real, across two dogfooding runs (a first-ever App Store submission, then
+  a from-zero Google Play listing to a live production release) and a later consumer store release (the
+  EAS Update lifecycle) — none is general knowledge restated.
 - Durable, store-specific platform facts are documented once in
   [`mobile-release-standards.md`](../../.arcane/governance/mobile-release-standards.md) and cited here
   by `MR-nn` ID; verification discipline is documented once in
@@ -42,6 +47,7 @@ account, not a local mistake.
 | `{EAS_PROJECT_SLUG}` | The EAS project ID/slug. | Resolve from `app.json`'s `expo.extra.eas.projectId` or `eas init` output; if unset, ask. |
 | `{ANDROID_PACKAGE}` | The Android application ID / package name. | Resolve from `app.json`'s `expo.android.package`; if unset, ask. |
 | `{ORG_NAME}` | The Expo/EAS organization name, if the project belongs to one. | Resolve from `eas.json` or the EAS dashboard; if not applicable, omit. |
+| `{XCODE_VERSION}` | The Xcode version a build machine running `eas build --local` is pinned to, as `xcodebuild -version` prints it (for example `26.2`). | Use the Xcode of the EAS build image the build profile selects (`build.<profile>.ios.image`, or the default image for the project's SDK): read `DTXcode` from an IPA EAS built with that profile (`2620` is Xcode 26.2), never one older than App Store Connect accepts for uploads; if no EAS-built IPA exists yet, ask. |
 
 ## Context files
 
@@ -111,8 +117,9 @@ This section is common setup both stores' deployments depend on. Do it once.
   pipeline, run the update job against that commit (for example with a `--commit-id <sha>` argument,
   where the pipeline takes one); from the CLI, run `eas update` from a checkout of that commit. Read
   `eas update`'s `Commit`, `Runtime version` and `Platform` lines, then prove the alignment by reading
-  the published update back (`eas update:view <group-id>`), never from pipeline status or the publish
-  step's own output alone (`EV-01`, `EV-02`).
+  the published update back (`eas update:view <group-id> --json`, whose `gitCommitHash` and
+  `runtimeVersion` name that commit and runtime; the human-readable view prints no commit), never from
+  pipeline status or the publish step's own output alone (`EV-01`, `EV-02`).
 - **🔴 Bundler transform caches do not key on `EXPO_PUBLIC_*` env vars.** On a persistent (self-hosted)
   build runner, the cache survives between runs, so an update published to one channel can ship
   another channel's inlined config — for example, a production build silently pointing at a development
@@ -144,6 +151,177 @@ expired App Store Connect session shows as a redirect carrying `authResult=FAILE
 
 ---
 
+## EAS Update lifecycle (both stores)
+
+A store release changes which phones an update can reach. This section covers what each release leaves
+behind and what surrounds it, in four parts: the runtimes older store versions keep running (part 1, a
+step of every store release), an in-app prompt that moves phones to the store (part 2, built into the app
+once), the toolchain of a machine running `eas build --local` (part 3, set up once per machine and
+checked before every store build), and when to announce a version as the latest (part 4, after the store
+offers it).
+
+### 1. OTA lifecycle and stranded runtimes
+
+- **Audit the live runtimes before every store build (`MR-15`).** With `runtimeVersion.policy:
+  appVersion`, every store version is its own runtime, and an update reaches only phones whose binary has
+  the same runtime version: a phone that never installs the next store version receives nothing new,
+  forever, with no error anywhere. List the store versions from each store console's release history (or
+  the release tags, where every store release is tagged), then read, for each, its runtime and commit, how
+  many phones it still has, and the last update it receives:
+
+  ```bash
+  eas channel:view <channel>
+  # the EAS branch the store channel points to
+  eas build:list --platform <ios|android> --app-version <version> --distribution store --status finished --json
+  # one store version's builds, with runtime.version and gitCommitHash
+  eas channel:insights --channel <channel> --runtime-version <runtime> --days 30
+  # the phones on one runtime, running its embedded bundle or an update (eas-cli 18.8.0 or later)
+  eas update:list --branch <eas-branch> --runtime-version <runtime> --limit 1 --json
+  # the latest update group that runtime receives, if any
+  ```
+
+  A runtime that never received an update has no update group, `eas update:list` shows only the most
+  recent groups (25 unless `--limit` says otherwise), and `eas build:list` returns at most 50 builds per
+  page, newest first, with TestFlight and other test builds among them, so neither the update list nor a
+  page of the newest builds can be the inventory. A binary built with `eas build --local` has no EAS build
+  record: its commit comes from the pipeline run or tag that produced it. Judge each runtime as it will
+  stand once this release ships: the version it replaces still receives updates today and stops receiving
+  updates the moment the release is out. For each runtime that will still have phones and no update path,
+  choose its route before the release ships: the backport recipe below, the store update prompt (part 2,
+  backported the same way), or the operator's decision to leave it stranded, written into the release
+  report.
+- **Never publish to an old runtime from a checkout whose native dependencies differ from that binary.**
+  This is the OTA/native alignment rule above (Cross-platform lessons), applied to a runtime that is no
+  longer current. When it is broken, the publish succeeds and the phones on that runtime download an
+  update that calls native code their binary does not have. expo-updates rolls an update back by itself
+  only when it crashes before its content first appears, and then does not launch it again on that
+  device; a crash after that point, such as a screen calling the missing module, comes back every time
+  that screen is reached, until a corrected update is published to that runtime.
+- **When a runtime is already crashing on a bad update, stop the damage first**, with the operator's
+  go-ahead, since each command publishes to phones in production: republish that runtime's last good
+  update group (`eas update:republish --group <last-good-group-id>`), or send the runtime back to the
+  bundle embedded in its binary
+  (`eas update:roll-back-to-embedded --channel <channel> --runtime-version <runtime>`). Then backport the
+  fix.
+- **The backport recipe for a stranded runtime:**
+  1. Find the commit that runtime actually runs. The audit's `eas update:list` line names its latest update
+     group, and `eas update:view <group-id> --json` gives that group's `gitCommitHash` (the human-readable
+     view prints no commit). A runtime that never received an update runs the bundle embedded in its store
+     build: take the `gitCommitHash` of that build's `eas build:list` entry, or, for a binary built with
+     `eas build --local`, the commit of the pipeline run or release tag that produced it.
+  2. Create a git branch from that commit and add only the files the fix needs, using only primitives that
+     binary has: no new native module, and no API from a newer SDK or a newer native dependency.
+  3. Build the workspace libraries first (in a monorepo, the packages the app imports), then typecheck
+     against that tree, not the trunk's.
+  4. With the operator's go-ahead (this publishes to phones in production), commit, then publish from that
+     git branch to the store channel:
+     `eas update --channel <channel> --environment <environment> --message "<what it fixes>"`, with the
+     store build's environment (usually `production`): the flag loads that environment's server-side
+     variables, which the publish otherwise leaves out, and clears the bundler cache. Never use `--auto`,
+     which names the EAS branch after the git branch, a branch no channel points to. The `Commit` line
+     `eas update` prints must not end in `*`, which marks an uncommitted tree.
+  5. Prove it by reading the update back: `eas update:view <new-group-id> --json` must show the stranded
+     runtime's `runtimeVersion`, the git branch's `gitCommitHash`, and the `branch` that
+     `eas channel:view <channel>` names. The pipeline's "succeeded" is not evidence (`EV-02`).
+  6. Mark the git branch publish-only (its name and its first commit say so) and never merge it: it exists
+     to publish from, and a merge would bring that old tree back into the trunk.
+
+### 2. A store update prompt
+
+Built into the app and its API once; it moves phones off old store versions instead of waiting for them.
+
+- **The server holds the versions:** a "latest version" and a "minimum version" per platform, editable by
+  an operator (an admin screen), empty by default. The client sends its platform and version, and the
+  server answers `ok`, `update` (an invitation with "not now", snoozed for a few days) or `required` (a
+  screen with only an update button, which cannot be closed).
+- **Clients identify themselves on every request.** From the release that introduces it, the client sends
+  its platform and version as request headers, and the API answers `426 Upgrade Required` to anything
+  below the minimum version, except the version-check endpoint itself. Older clients that send no headers
+  pass. This is the emergency brake for a breaking API change, and it answers "which app versions still
+  call this route?" before any `/v2` is needed.
+- **Mount the prompt outside the app's error boundary.** A 426 can make a screen throw, and an error
+  boundary whose fallback replaces the whole tree replaces the update screen with it.
+- **Word the mandatory screen as something new, not something broken:** "there is a new version", not
+  "this version no longer works".
+- **Backport the prompt to every stranded runtime** (part 1): for those phones it is the only way to the
+  store.
+
+### 3. Toolchain pinning for self-hosted build agents
+
+Applies when `eas build --local` runs on a machine whose Xcode can change between builds: a Mac you
+manage, or a hosted CI runner whose default Xcode moves with its image. EAS's own build servers run the
+image the build profile selects.
+
+- **Pin the Xcode per build (`MR-16`).** Install the pinned version beside any newer one as
+  `/Applications/Xcode-{XCODE_VERSION}.app` (on a hosted runner, point `DEVELOPER_DIR` at that version
+  among the image's preinstalled Xcodes instead), set `DEVELOPER_DIR` to its `Contents/Developer` for the
+  whole build job so that every step uses it, the build included, and add a bash guard step that fails
+  the run when the path is missing or `xcodebuild -version` reports another version:
+
+  ```bash
+  set -euo pipefail
+  expected="Xcode {XCODE_VERSION}"
+  if [ ! -d "${DEVELOPER_DIR:?DEVELOPER_DIR is not set}" ]; then
+    echo "Pinned Xcode is not installed: $DEVELOPER_DIR" >&2
+    exit 1
+  fi
+  version_output="$(xcodebuild -version)"   # captured whole, never piped into head
+  read -r first_line <<< "$version_output"
+  if [ "$first_line" != "$expected" ]; then
+    echo "Expected $expected, xcodebuild reports: $first_line" >&2
+    exit 1
+  fi
+  ```
+
+  Avoid `xcodebuild -version | head -1` under `pipefail`: `head` can exit before `xcodebuild` has finished
+  writing, the SIGPIPE that ends `xcodebuild` fails the pipeline, and the step dies (exit 141).
+- **Before a store build on such a machine, read the guard's result in that build's own run.** Confirm that
+  the job ran the guard step and that it passed; stop the release if the step is missing or failed.
+- **Move the pin only with the EAS build image the build profile selects** (`build.<profile>.ios.image`,
+  or the default image for the project's SDK). An IPA that EAS built with that profile records the Xcode
+  it used as `DTXcode` in its `Info.plist` (`2620` is Xcode 26.2); pin that version, and never one older
+  than App Store Connect accepts for uploads.
+- **When a store build crashes at launch but the same JavaScript runs fine via OTA**, compare `DTXcode` and
+  `DTSDKName` in the working and the crashing IPA's `Info.plist` (unzip each IPA, then
+  `plutil -p Payload/<App>.app/Info.plist` on macOS) before reading any code, and build the same commit in
+  the EAS cloud: if that build works, the toolchain is the difference, not the code (`MR-16`).
+
+### 4. When to set "latest"
+
+- **Set the server-side "latest version" for a platform only when that store's listing actually offers
+  the version.** Set early, it sends users to a store page that still offers the old build.
+- **Raise the "minimum version" only to a version every user can install now:** on the App Store once the
+  lookup below reports it, on Google Play once the production rollout reaches 100%. A minimum above that
+  leaves users on a screen that cannot be closed, whose only button opens a store page that still offers
+  the old build, while the API refuses their every request with 426. A version that raises the iOS
+  deployment target or Android's `minSdkVersion` never installs on devices below it, so a minimum at that
+  version locks those devices out for good, unless the client also sends its OS version and the server
+  exempts them.
+- **App Store:** the public lookup, `https://itunes.apple.com/lookup?bundleId={IOS_BUNDLE_ID}`, returns the
+  listed version as `results[0].version`. Show it beside the admin field as a reference, with a warning
+  when the typed version is newer. It reads one storefront, the United States unless `&country=<cc>` names
+  another (`resultCount: 0` means the app is not listed there), and it answers from a cache (a `max-age`
+  of about 2 to 14 hours in checks on 2026-10-22), so a version released in the last several hours can
+  still read as the old one: treat the warning as a reason to check the listing by hand.
+- **Google Play publishes no equivalent lookup**, so Play is a manual check of the listing before either
+  field is set, and a staged rollout counts only at 100%: until then, some users are still offered the
+  previous build.
+
+**Observed in one consumer session (reported 2026-10-18), not re-verified since** — re-check before relying
+on any of them: phones on five earlier store versions had received no update for weeks before anyone
+noticed; one runtime crash-looped on an update published from a checkout with a different native SDK, and
+the session described expo-updates rolling back to the previous update on every launch while the latest
+update on the channel kept breaking it (compare the documented behavior in part 1); two production iOS
+binaries crashed at launch after the build Mac's Xcode updated itself, while the same JavaScript ran fine
+via OTA; and a 426 made the app's feed crash, so the error boundary's fallback replaced the update screen
+until the prompt was mounted above the boundary.
+
+Enforcement: parts 1 and 3 are structured spell gates through `MR-15` and `MR-16` (ARC-023); parts 2 and
+4 are explicitly advisory prose (ARC-023) — the prompt and the server-side fields are the app's own code,
+which no step of this spell can read.
+
+---
+
 ## Apple App Store
 
 ### Initial one-time setup
@@ -162,6 +340,8 @@ expired App Store Connect session shows as a redirect carrying `authResult=FAILE
 
 ### Repeat deployments
 
+Start with the runtime audit (EAS Update lifecycle, part 1; `MR-15`), then build and submit:
+
 ```bash
 eas build --platform ios --profile production
 eas submit --platform ios --profile production --latest
@@ -217,6 +397,8 @@ each require one independently.
 
 ### Repeat deployments
 
+Start with the runtime audit (EAS Update lifecycle, part 1; `MR-15`), then build and submit:
+
 ```bash
 eas build --platform android --profile production
 eas submit --platform android --profile production --latest
@@ -269,7 +451,8 @@ console error stating otherwise (`EV-06`).
 
 ### Reporting the release
 
-End every release run with a short report. The store-console steps the agent cannot reach — sending
+End every release run with a short report that includes the runtime audit's result (each runtime still on
+phones and the route chosen for it). The store-console steps the agent cannot reach — sending
 staged Google Play changes for review, answering an App Store review question, confirming a manual
 release — are required operator actions:
 

package/dist/assets/.arcane/spells/spell-test.md

@@ -11,6 +11,9 @@ agent: agent
 - This prompt runs tests, validates coverage against thresholds, and generates evidence artifacts.
 - Used after `spell-implement` to verify quality before `spell-review`.
 - Enforces the testing standards from ADR-050 (80% line / 95% critical path coverage).
+- For anything a browser renders, step 4a adds a check in a real browser (captures at three widths, in both
+  color schemes and with reduced motion, plus a console read), because a passing suite cannot see a page
+  that renders blank.
 - See [[.arcane/governance/testing-standards|Testing Standards]] for framework details.
 
 ---
@@ -48,6 +51,49 @@ Workflow:
    - Map each acceptance criterion from the story to a specific test.
    - Flag any acceptance criteria without corresponding test coverage.
 
+4a. **Visual verification (HTML and UI deliverables)** — run this step when the scope changes anything a
+   browser renders: a page, a template, a stylesheet, a UI component. A passing suite is not evidence that
+   a page renders; a page cut short arrives blank, and only a browser shows it. For each changed page or
+   screen:
+   - **Serve it over local HTTP, never `file://`,** with the headers production sends: the project's own
+     dev or preview server, or a static server configured with the same `Content-Type` (adding no charset
+     production does not send) and the same security policy. Check that the page declares its character
+     set (`<meta charset="utf-8">` within its first 1024 bytes): a page that does not can read correctly
+     from disk and still garble when served without a charset, and a content security policy sent as a
+     response header never applies to a `file://` load.
+   - **Capture it headless at 1440, 390 and 320 px wide, in dark and in light, each with motion allowed and
+     with reduced motion:** twelve full-page captures per page. Before each capture, reduced motion
+     included, wait until `document.getAnimations()` reports none whose `playState` is `"running"`, with a
+     time limit; a page that still moves content under reduced motion (a slide, a zoom, parallax) is a
+     finding of its own, while a fade or a progress indicator may stay. For a page that
+     animates without end, capture with `page.screenshot({ animations: "disabled" })` instead; the evidence
+     says which method was used. Any headless browser that can set the viewport and emulate both media
+     features will do; in Playwright that is `page.setViewportSize`,
+     `page.emulateMedia({ colorScheme, reducedMotion })` and `page.screenshot({ fullPage: true })`.
+   - **Read the console for every capture.** Script errors, uncaught exceptions and content-security-policy
+     violations each count, and the bar is zero. In Playwright, listen to `page.on("console")` and
+     `page.on("pageerror")` before the page loads, so nothing logged during the load is missed.
+   - **Compare before and after.** Capture the same matrix from the base branch, or from the last release,
+     in the same session, on the same machine and browser, with time and data held still (fixture data, a
+     fixed clock such as Playwright's `page.clock`), and compare each capture with its counterpart. An
+     unchanged page then captures identically, so a difference the change did not intend is a finding,
+     like a failing test. A page new in this change has no before set: review its after set by eye.
+   - **Keep the captures in the design record:** the feature's folder, `features/<feature>/visual/YYYY-MM-DD/`
+     (outside a feature, `assets/screenshots/YYYY-MM-DD/`), named `<page>-<width>-<scheme>-<motion>.png` and
+     linked from the story's `testEvidence`. Keep each after capture that differs from its before capture,
+     that before capture, and one reference capture per page; record the rest by hash, noting any
+     dimension the page does not respond to (dark and light on a page with one color scheme). Never keep a
+     capture that shows a secret, a token or personal data (universal agent rules, Screenshot Curation):
+     capture with fixture data, or mask the region with `page.screenshot({ mask: [locator] })`. In a
+     repository whose `.arcane.json` sets `content_sensitivity: "sensitive"`, keep no captures: record each
+     capture's verdict and a sanitized summary with no recoverable detail (universal agent rules, Sensitive
+     Repositories).
+   - **No headless browser available:** say so and record the visual check as `NOT RUN`, never `PASS`; the
+     story stays open until someone runs it.
+   - Enforcement: structured spell gate (ARC-023) — this spell's Rules keep a story with a rendered
+     deliverable from passing until this step's result is recorded; no executable check reads the
+     captures.
+
 5. **Generate test evidence**:
    ```markdown
    ## Test Evidence — [Story ID or Scope]
@@ -67,6 +113,13 @@ Workflow:
    | ----------- | ----------- | ----------------- |
    | [criterion] | [test name] | PASS/FAIL/MISSING |
 
+   ### Visual Verification (step 4a, when the scope renders in a browser)
+   - Served from: [local URL, with production's headers; never file://]
+   - Captures: [12 per page: 1440/390/320 px × dark/light × motion/reduced, and the wait method]; kept in [design-record path]: [differing pairs, one reference per page]; the rest by hash
+   - Console: [0 errors, or each error and policy violation]
+   - Before/after: [no unintended difference, or each one]
+   - Status: PASS / FAIL / NOT RUN — [reason]
+
    ### Uncovered Areas
    - [file:lines with no coverage]
 
@@ -77,12 +130,14 @@ Workflow:
 6. **Update stories.json** — if testing a specific story, update the `testEvidence` field.
 
 7. **Report** — present the test evidence and recommend next steps:
-   - All pass + coverage met → recommend `spell-review`.
+   - All pass + coverage met (and step 4a passed, where it applies) → recommend `spell-review`.
    - Failures found → recommend fixing via `spell-implement`.
    - Coverage gap → recommend adding tests before review.
 
 Rules:
 - Never mark a story as passing if tests fail or coverage is below the threshold.
+- Never mark a story whose scope a browser renders as passing until step 4a's result is recorded (its
+  captures, or in a sensitive repository their sanitized summary); a `NOT RUN` visual check keeps it open.
 - Include actual test output, not just summaries.
 - If no test framework is set up, flag this as a blocker and recommend setup.
 - Critical path code (auth, payments, data mutations) must meet the 95% threshold.