@deeeed/metamask-harness 0.2.0

package/docs/MENTAL-MODEL.md

@@ -0,0 +1,295 @@
+# mm-harness — Mental Model (review first)
+
+Read this before the code. It is the before→after map for the CLI refactor. Every
+"today" command below is real (from `bin/mm-recipe`, `bin/mme-recipe`,
+`runner/src/cli.ts`, and the `recipe-harness` skill) — nothing invented.
+
+> Skimmable overview. The detailed contract — a complete capability inventory
+> (every verb, with a fate), a per-verb spec, the caller audit, and the env-var
+> audit — is in [CLI-SPEC.md](CLI-SPEC.md).
+
+## The model in one paragraph
+
+**`mm-harness` is built for the agent but easy for the human to use and
+understand.** It is the one front door for the whole recipe loop. The agent gets
+full depth (explicit flags, `--json`, ports, build tiers — machine-grade
+determinism); the human gets short verbs, positional targets, good defaults,
+completions, and teaching help/errors. Under it: the **engine** is
+`@farmslot/recipe-harness` (generic graph execution, adapters, recording, CLI);
+the **runner** (this repo) is the thin **MetaMask adapter** layer (manifests,
+`metamask.*` live adapters, orchestration); the **runtime overlay** is the set of
+files the tool installs into a target checkout (`install`/`verify`/`cleanup`).
+The runner never re-implements engine logic — it imports it. The agent
+composition loop is the harness's thesis made concrete: **discover** actions and
+browse flows (`actions --json` / `flows --json`) → **call** one action in
+isolation to verify it (`call <action> --json`) → **compose** a `recipe.json` →
+**plan** before any device is touched (`run --plan`) → **run** → review
+evidence (`summary.json` / `trace.json`). `run --plan` closes the loop: adapter-aware
+validation (action existence, platform support, fixture preconditions) exits fast
+with a reviewable plan artifact — wrong recipes fail before any device is touched.
+
+## Organizing rule (Arthur)
+
+Identify the MAIN commands a human types daily, then each subcommand — always
+optimizing "how simple for the human," with advanced options for the agent and
+good defaults for easy typing. Enforced rules, visible in every table below:
+
+- **Grammar:** `mm-harness <verb> [target] [flags]`. Target is a positional
+  (`ios` | `android` | `extension`) — the human form. The equivalent explicit
+  flag (`--platform …`) is the agent form.
+- **Depth lives in FLAGS, never in extra command names.** If a daily task needs
+  >1 flag (or >1 step) for a human, the default is wrong — a `[DEFAULT-GAP]`.
+- **No env-var prefixes for humans.** `VAR=x mm-harness …` is agent/CI syntax
+  only; a human-typed value that has no flag/config home is an `[ENV-GAP]`.
+- **One bin, clean break.** End state has exactly one command, `mm-harness`. The
+  `metamask-recipe` / `mm-recipe` / `mme-recipe` names and the `harness <verb>`
+  subcommand form are REMOVED in the same coordinated wave; their capabilities
+  live at their final `mm-harness` home (Part 2 of the spec).
+- **A verb's most common action is its default action.** `mm-harness flows` lists;
+  `mm-harness flows promote` is the explicit subcommand. Never force the user to
+  type `list` when listing is what the verb does by default.
+- **Direct action names are not top-level verbs (REJECTED).** `mm-harness unlock`
+  is rejected — an open action vocabulary collides with the verb namespace; hot
+  actions get deliberately promoted to real verbs instead. Use
+  `mm-harness call unlock` (fuzzy short-name resolution to `metamask.wallet.unlock`
+  when unambiguous).
+- **The overlay is per-checkout, git-ignored plumbing — humans never manage it.**
+  Daily verbs (`launch`, `run`) check for the overlay at startup and
+  auto-install it inline with a one-line notice on first run on that checkout.
+  `install` is the explicit form for CI, agents, and deterministic setup
+  (`--heal=off` on daily verbs disables the inline check and all healing).
+- **Your slot's settings live in `agentic-runtime.json` — `doctor` explains them;
+  you never hunt for the file.** `doctor` prints every field (slotId, extensionId,
+  cdpPort, runtimeStart.*), its current value, its source (file / env var /
+  default), and exactly how to change it. Arthur's rule made concrete: no
+  knowledge lock-in about which file to edit.
+- **Verbs are idempotent — they make reality match intent; the recovery command is
+  the normal command.** `launch` and `run` detect broken runtime state
+  (Metro dead, Chrome/CDP offline, stale tabs) and heal before proceeding (controlled
+  by `--heal`; default `auto` for `launch`, `infra-only` for `run`). The
+  agent does not need a separate recovery verb: re-running `mm-harness launch ios`
+  IS the recovery. `--json` reports what was healed in a `recovered:[...]` field
+  (stable codes). `recoverable:false` + `attemptedRecoveries[]` stop agent retry
+  loops when bounds are hit. `doctor --fix` repairs without launching when healing
+  alone is the goal.
+
+## Status legend
+
+| Tag | Meaning |
+|---|---|
+| **ROUTES-NOW** | Works today through `mm-harness` (this draft) |
+| **STUB** | `mm-harness` verb exists but exits 2 and teaches the working command; spec'd in Part 2 |
+| **ABSORB-LATER** | Capability folds into an `mm-harness` verb (spec'd in Part 2 with a maps-to row) |
+| **KEEP-INTERNAL** | Still reachable, just not a user-facing verb |
+| **REMOVE** | Name/bin/subcommand deleted in the refactor wave; callers updated in the same wave (needs sign-off) |
+
+## Bin & name table (before → after)
+
+| Before | Role today | After |
+|---|---|---|
+| `bin/metamask-recipe` | public typed CLI + platform passthrough | **REMOVE** — becomes `bin/mm-harness` (same entrypoint, one name); no alias kept |
+| `metamask-recipe harness <verb>` | overlay lifecycle subcommand | **REMOVE** — verbs live top-level (`mm-harness install/verify/cleanup`); `live` dissolved into `launch --verify` |
+| `bin/mm-recipe` | mobile porcelain (Metro/sim/bridge) | **REMOVE** — capabilities become `mm-harness` verbs (Part 2); impl kept internal |
+| `bin/mme-recipe` | extension porcelain (Chrome/CDP) | **REMOVE** — capabilities become `mm-harness` verbs (Part 2); impl kept internal |
+| `recipe-harness` skill (~812 lines bash) | overlay lifecycle | **REMOVE** — thins to a caller of `mm-harness` overlay verbs |
+| `completions/_recipe` (zsh; completes `recipe mme-recipe mm-recipe`) | shell completion | **REMOVE** — replaced by bundled `mm-harness` completions (zsh + bash), auto-installed on setup |
+
+**`bin/mm-harness`** is the one user bin. **No per-platform binaries** —
+`mm-mobile-harness` / `mm-extension-harness` are rejected (recreates the
+three-names problem). Platform = auto-detected context; the positional target
+forces it; platform-specific needs are FLAGS on the same verb.
+
+---
+
+## BEFORE → AFTER by main command
+
+Columns: **Human form** (bare verb / positional target; zero env prefixes;
+defaults stated) · **Agent / advanced form** (explicit flags, `--json`) · **Status**.
+
+### DAILY LOOP
+
+#### `launch` — start the app (Metro/build + boot)  ·  REAL (wave 3)
+
+Auto-ensures runtime overlay before launching (installs inline with a one-line notice on first run; `--heal=off` to disable). **Idempotent + self-healing (default `--heal=auto`):** detects broken runtime state (Metro dead, Chrome/CDP offline, stale home tabs) and recovers before launching. The agent's recovery command is simply `mm-harness launch <target>` — no separate recovery verb. `--json` gains `"recovered": ["metro.restarted", ...]` (stable codes); `recoverable:false` + `attemptedRecoveries[]` stop retry loops. **`--verify`:** after launch, polls CDP/bridge until ready + runs smoke verify — implements the retired `live` sequence (zero capability lost). **Change detection:** quick launch (no `--build`) checks native/webpack build inputs; if changed → refuses with teaching error pointing at `--build`. Phase state-machine: `resolve → install → healthcheck → recover → launch → verify`.
+
+| | |
+|---|---|
+| **Human form (mobile)** | `mm-harness launch ios` · `mm-harness launch android` — target **MANDATORY**; missing → teaching error: "specify ios or android" |
+| **Human form (extension)** | `mm-harness launch` (no target; default `--fullscreen`; `--sidepanel` to open sidepanel mode) |
+| **Quick vs full build** | bare `launch` = quick relaunch (no native/webpack build); `--build` = full build first |
+| **Runway (mobile only)** | `--runway` runs a post-launch runway check; teaching error on extension |
+| **`live` replacement** | `mm-harness launch ios --verify` (install overlay → launch → poll → smoke verify — never seeds fixtures) |
+| **Agent / advanced** | `mm-harness launch --platform ios --device <udid> --build --verify --heal=off --json` |
+
+| Today (real) | → mm-harness | Status |
+|---|---|---|
+| `mm-recipe ios` · `android` · `start` | `launch ios\|android` (positional, mandatory) | ABSORB-LATER |
+| `mm-recipe up` | `launch ios --build` | ABSORB-LATER · [DEFAULT-GAP] tier hidden behind `MOBILE_PREFLIGHT_MODE=…` [ENV-GAP] |
+| `mm-recipe refresh` · `reload` · `relaunch` | `launch ios\|android` (quick) | ABSORB-LATER |
+| `mme-recipe rebuild` · `reopen` · `browser` · `launch` · `reload` · `reset` | `launch` (quick, extension) | ABSORB-LATER |
+| `mme-recipe up` | `launch --build` (extension) | ABSORB-LATER |
+| `mme-recipe watch` **then** `rebuild` | `launch --watch` (extension) | ABSORB-LATER · [DEFAULT-GAP] two commands today |
+| `mme-recipe build` · `refresh` · `refresh-once` | `launch` tiers (extension) | ABSORB-LATER |
+| `mme-recipe sidepanel [cycle\|open]` | `launch --sidepanel` (extension) | ABSORB-LATER |
+
+#### `logs` — tail Metro/webpack + app logs  ·  REAL (wave 3)
+
+| | |
+|---|---|
+| **Human form** | `mm-harness logs` (compact, auto platform) |
+| **Agent / advanced** | `mm-harness logs --full --platform mobile --json` |
+
+| Today (real) | → mm-harness | Status |
+|---|---|---|
+| `mm-recipe logs` · `tail` · `logs --full` | `logs [--full]` | ABSORB-LATER · [ENV-GAP] `RECIPE_LOG_UI`/`RECIPE_LOG_EVENTS` → flags |
+| `mme-recipe logs` · `tail` · `tail-webpack` | `logs` | ABSORB-LATER |
+
+#### `debug` — open the debug console  ·  REAL (wave 3)
+
+| | |
+|---|---|
+| **Human form** | `mm-harness debug` (auto platform) |
+| **Agent / advanced** | `mm-harness debug --worker` (extension SW) · `--dev-menu` · `--platform mobile` |
+
+| Today (real) | → mm-harness | Status |
+|---|---|---|
+| `mme-recipe debug` · `devtools` · `inspect` · `debug worker` | `debug [--worker]` | ABSORB-LATER |
+| `mm-recipe debug` | `debug` | ABSORB-LATER |
+| `mm-recipe dev-menu` · `devmenu` | `debug --dev-menu` (flag) | ABSORB-LATER · [DEFAULT-GAP] separate verb for one console concept |
+
+#### `fixtures` — sync fixture files + set up the wallet  ·  REAL (wave 3)
+
+One canonical wallet fixture per checkout (SSOT). Fixture status is reported by `doctor` automatically (grounded: `fixtureSummary()` in `runner/src/doctor.ts`). `fixtures` group = `sync` and `set` only — no bare status verb.
+
+Subcommands: `fixtures sync`, `fixtures set`.
+
+| | |
+|---|---|
+| **Human form** | `mm-harness fixtures sync` · `mm-harness fixtures set` (applies THE canonical fixture — password read FROM the fixture, never typed; always prints "Want different accounts? Edit: <path>/wallet-fixture.json") |
+| **Agent / advanced** | `mm-harness fixtures set --fixture <json> --platform mobile` (`--fixture` is agent-only; humans edit the canonical file directly) |
+
+| Today (real) | → mm-harness | Status |
+|---|---|---|
+| `mm-recipe sync` · `mme-recipe sync` | `fixtures sync` | ABSORB-LATER |
+| `mme-recipe update` · `sync-runtime` | `fixtures sync` | ABSORB-LATER |
+| `mm-recipe setup-wallet` · `wallet-setup` | `fixtures set` | ABSORB-LATER · [ENV-GAP] `RECIPE_WALLET_FIXTURE` → `--fixture` (agent-only) |
+| `mm-recipe setup:ios` · `setup:android` | `launch ios` **then** `fixtures set` | ABSORB-LATER |
+| `mm-recipe unlock` | `fixtures set` (password from fixture) | ABSORB-LATER · [ENV-GAP] `MM_PASSWORD=… unlock` is the anti-pattern — read the fixture |
+| Extension standalone wallet setup | `fixtures set` | **[GAP]** no standalone verb today — the first-run wallet is seeded by the legacy `mme-recipe up`; end-state home is `fixtures set` (launch / `launch --verify` never seed) |
+
+### DISCOVER  (agent composition layer — `--json` is PRIMARY)
+
+The composition loop: `actions --json` → `call <action>` (try one via real engine path) → `flows --json` → compose `recipe.json` → `run --plan` (adapter-aware validate + plan, no device) → `run`.
+
+`manifest` is **RETIRED**: raw protocol dump → `actions --raw`; validation → `run --plan` / `doctor`. `validate` verb **DISSOLVED** into `run` (`run` validates first; `run --plan` = plan-only; same or richer shape, plus adapter cross-check). **DISCOVER final shape: `actions` · `call` · `flows`** — no manifest verb, no validate verb. Shell completions are sourced from this same layer: `call` completes action names, `run`/`run --plan` complete flow refs, both with a per-checkout short-TTL cache.
+
+#### `actions` · `call` · `flows`  ·  ROUTES-NOW (call: REAL wave 2)
+
+| | |
+|---|---|
+| **Human form** | `mm-harness actions --adapter mobile` · `mm-harness call unlock` · `mm-harness flows` |
+| **Agent PRIMARY** | `mm-harness actions --adapter mobile --json` → `{ adapter, actions: [{ name, kind, description, fields, examples }] }` |
+| | `mm-harness call metamask.perps.read_positions --arg symbol=BTC --adapter core --json` → `{ action, resolvedAction, args, trace, evidence, recovered, mutations, exitCode, schemaVersion }` (same shape as `run --json`, one-node subset) |
+| | `mm-harness flows --json` → `{ sources, flows: [{ ref, source, file, description?, requiredParams?, shadows?, lastVerified? }] }` |
+| **Plan before run** | `mm-harness run recipe.json --plan --json` → `{ plan[], validation: { status, findings }, schemaVersion }` (adapter-aware; exit 5 on errors) |
+
+| Today (real) | → mm-harness | Status |
+|---|---|---|
+| `metamask-recipe actions --adapter …` | `mm-harness actions --adapter …` | ROUTES-NOW · [DEFAULT-GAP] `--adapter` required · [DISCOVERY-GAP] no `--action <name>` filter, no `--kind` filter, no keyword search |
+| `metamask-recipe flows list\|promote` | `mm-harness flows [\|promote]` | ROUTES-NOW · `flows` = browse the reusable flow library (compose, don't rewrite); `promote` publishes a proven flow up a tier · bare `flows` = list · [DISCOVERY-GAP] no keyword filter, no per-flow body fetch, no platform filter |
+| `mm-recipe`/`mme-recipe` `actions`/`doctor` (auto adapter) | same `mm-harness` verbs | ABSORB-LATER — porcelain supplies missing adapter default |
+| hook layer `run-action app.unlock` | `mm-harness call unlock` (fuzzy: `unlock` → `metamask.wallet.unlock`) — **one-node recipe via real engine path** | REAL (wave 2) · ambiguous → exit 2 listing candidates |
+| `mm-harness validate recipe.json` (old stub) | `mm-harness run recipe.json --plan` | **DISSOLVED** — stub teaching message updated to point at `run --plan`; `validate-command.ts` called internally by run engine (phase: `validate`) |
+
+### PROVE
+
+#### `run` — validate + execute a recipe, write evidence  ·  ROUTES-NOW
+
+**Validates first (adapter-aware):** before touching any device, `run` checks action existence, platform support, and fixture preconditions. Exit 5 on validation errors (same code for `run`, `run --plan`, `call`). `--plan` = plan-only: prints what would happen, touches NO device, exits 0/5. Phase state-machine: `resolve → install → healthcheck → recover → validate → launch → execute`. `--heal` defaults `infra-only`; healing never touches wallet state — only the explicit `fixtures set` mutates it.
+
+| | |
+|---|---|
+| **Human form** | `mm-harness run recipe.json` (adapter + artifacts auto-defaulted) |
+| **Plan before run** | `mm-harness run recipe.json --plan` (adapter-aware; no device; exit 0 = valid, exit 5 = errors) |
+| **Agent / advanced** | `mm-harness run recipe.json --adapter mobile --project-root <repo> --artifacts-dir <dir> --record-video=full-run --heal=off --json --json-stream` |
+
+| Today (real) | → mm-harness | Status |
+|---|---|---|
+| `metamask-recipe run … --adapter … --artifacts-dir …` | `mm-harness run …` | ROUTES-NOW · [DEFAULT-GAP] `--adapter` + `--artifacts-dir` mandatory today · [ENV-GAP] `RECIPE_LIBRARY_PATH` → `--library`/config |
+| `mm-recipe run recipe.json` · `mme-recipe run recipe.json` (auto adapter+artifacts) | `mm-harness run recipe.json` | ABSORB-LATER — porcelain already supplies the good defaults the typed CLI lacks |
+
+#### `doctor`  ·  ROUTES-NOW
+
+Pure read-only diagnostic. Absorbs the retired `manifest` verb's validation: readiness checks include manifest well-formedness + reports manifest path + protocol version. `--fix` mode runs healing without launching (same path as `launch`/`verify` self-healing but stops short of starting the app).
+
+| | |
+|---|---|
+| **Human form** | `mm-harness doctor` |
+| **Agent / advanced** | `mm-harness doctor --adapter mobile --target <repo> --json` |
+| **Repair without launch** | `mm-harness doctor --fix [--json]` → `{ ..., "fixed": [...], "failed": [...] }` |
+
+| Today (real) | → mm-harness | Status |
+|---|---|---|
+| `metamask-recipe doctor --adapter … --target …` | `mm-harness doctor` | ROUTES-NOW · [DEFAULT-GAP] `--adapter`+`--target` required |
+| `mm-recipe`/`mme-recipe` `doctor` (auto adapter/target) | `mm-harness doctor` | ABSORB-LATER — porcelain supplies the missing defaults |
+
+### RUNTIME OVERLAY
+
+#### `install` · `verify` · `cleanup`  ·  ROUTES-NOW
+
+`live` is **REMOVED** — dissolved into `launch --verify` (same sequence: install overlay if missing → launch → CDP poll → smoke verify; zero capability lost — `launch --verify` never seeds fixtures).
+
+| | |
+|---|---|
+| **Human form** | `mm-harness install` · `verify` · `cleanup` (platform auto-detected, target = cwd) |
+| **`live` replacement** | `mm-harness launch [ios\|android] --verify` |
+| **Agent / advanced** | `mm-harness verify --platform extension --target <repo> --json -- --cdp-port <port>` |
+
+| Today (real) | → mm-harness | Status |
+|---|---|---|
+| `recipe-harness install\|verify\|cleanup\|live …` (skill) | `mm-harness install\|verify\|cleanup` · `live` → `launch --verify` | ROUTES-NOW; skill REMOVE |
+| `metamask-recipe harness install\|verify\|cleanup\|live …` | `mm-harness install\|verify\|cleanup` (top-level) · `live` → `launch --verify` | ROUTES-NOW; `harness` prefix REMOVE |
+| `mm-recipe prepare` · `mme-recipe prepare` | `install` / `launch` prep | ABSORB-LATER |
+| `mme-recipe ready` · `ensure-ready` | `verify` (or advanced `ensure-ready`) | ABSORB-LATER |
+
+### ADVANCED (agent / internal — rarely typed by hand)
+
+| Today (real) | → mm-harness | Status |
+|---|---|---|
+| `metamask-recipe runtime-health` · `runtime-decision` · `runtime-launch` · `resolve-extension` · `ensure-ready` · `self-test` | logic moves INSIDE `launch`/`verify` self-healing path — no user-facing verb; `self-test` callable via `package.json` scripts only | KEEP-INTERNAL |
+| `metamask-recipe manifest --adapter …` | **RETIRED** — (1) validation → `doctor` readiness check; (2) raw dump → `mm-harness actions --raw`; (3) path + protocol version → `doctor` explain-my-setup | REMOVE |
+| `mm-recipe`/`mme-recipe` `runtime-status` · `decision` · `ports` · `status\|home\|health` · `stop` | operator/infra flags on `mm-harness` (e.g. `--json` status) | ABSORB-LATER |
+| `mm-recipe`/`mme-recipe` `completion\|complete` | bundled `mm-harness` completions (dynamic from DISCOVER layer) | KEEP-INTERNAL / REMOVE (old `_recipe`) |
+| `mm-recipe`/`mme-recipe` `interactive\|menu` | interactive shell | ABSORB-LATER |
+| `mm-recipe` bridge verbs: `app-status` · `route` · `navigate` · `back` · `accounts` · `select-account` · `screenshot` | recipe-driven or future flags | ABSORB-LATER |
+
+---
+
+## Decisions (final)
+
+The surface below is settled — the design passed a three-round external review (final verdict: SOUND). The rulings that shape day-to-day use:
+
+- **One bin, clean break.** `mm-harness` is the only command; `metamask-recipe` / `mm-recipe` / `mme-recipe` and the `harness <verb>` form are removed in the coordinated caller-sweep wave (CLI-SPEC.md Part 3).
+- **DISCOVER = `actions · call · flows`.** `manifest` is retired (raw dump → `actions --raw`; validation → `run --plan` / `doctor`; path + protocol version → `doctor`). `validate` is dissolved into `run` (`run` always validates first; `run --plan` = plan-only, no device).
+- **`call` is a one-node recipe** through the real engine path — same trace / evidence / `--json` shape as `run`; one execution path, two doors. `call` inherits `run` semantics in full (default `--heal=infra-only`).
+- **`live` is dissolved into `launch --verify`** (install overlay → launch → CDP poll → smoke verify; zero capability lost — `launch --verify` never seeds fixtures). No `live` verb on any surface.
+- **`--heal` = `off | infra-only | auto`** (+ `--yes` for non-interactive confirmation). `launch` defaults `auto`; `run` and `call` default `infra-only`; `off` is repro-preserving and also disables auto-install. Recovery bounds are ALWAYS enforced (recipe running / app-logic failure / same recovery already failed once → `recoverable:false`); no flag bypasses them. `--heal=off` is the single opt-out (it also disables auto-install).
+- **Wallet state is mutated ONLY by the explicit `fixtures set`.** Healing never touches wallet state — overlay / Metro / Chrome recovery is infra; wallet data is not. If recovery would require a wallet write, the verb stops with `recoverable:false` and `userAction: "run mm-harness fixtures set"`. `fixtures` is wallet DATA only and never touches the overlay.
+- **Overlay install notice** (not a "consent print"): stderr-only in human mode; in `--json` it appears solely as `mutations[]`, so stdout stays clean for machines.
+- **Exit code 5 = validation failure everywhere** (`run`, `run --plan`, `call`) — no mode-specific meanings. `run --plan` items carry `confidence: static | conditional` so a plan never claims live runtime facts. Full taxonomy + agent error contract: CLI-SPEC.md Part 5.
+- **Agent error contract:** structured `error:{code,message,cause,retryable,userAction}`, stable `recovered[]` / `mutations[]`, a phase state-machine, JSONL `--json-stream`, and `recoverable:false` + `attemptedRecoveries[]` to stop retry loops (CLI-SPEC.md Part 5).
+- **Quick-launch change detection:** before a quick launch (no `--build`), `launch` checks native/webpack build inputs; if changed → teaching error pointing at `--build`. Never runs on a stale build.
+- **Daily verbs auto-ensure the overlay**; humans never run `install`. `install` / `verify` / `cleanup` are the explicit top-level forms for CI/agents.
+- **`flows` bare = list**; `flows promote` is the explicit subcommand.
+- **Implementation:** `commander` (the library `@farmslot/recipe-harness` already uses) + bundled dynamic zsh/bash completions sourced from the DISCOVER layer.
+
+**Deferred to later waves (sequencing, not open questions):** the `[DEFAULT-GAP]` auto-defaults (adapter/artifacts for `run` / `doctor` / `actions`), the `[ENV-GAP]` env→flag moves (CLI-SPEC.md Part 4), the caller sweep that deletes the old names (Part 3), and the repo rename.
+
+### Considered and rejected
+
+- **Teaching-tombstone stub bins** (`mm-harness-legacy`, etc.): Rejected. Pre-adoption burden with zero payoff; the coordinated wave (CLI-SPEC.md Part 3) updates all callers atomically. No tombstone bins needed.
+
+## How farmslot calls mm-harness (preflight & the fleet binding)
+
+"Preflight" survives as a capability, not an exposed concept: it is what `launch` does before returning (readiness: Metro/bundle → app → health/bridge poll), with `launch --verify` as the prove-it tier and `doctor` as the read-only view. The fleet is just another agent-grade caller — farmslot prepare profiles keep their git / fixtures / deps phases, and the preflight/health hooks collapse to one call: `mm-harness launch <target> --verify --heal=auto --json`. Same-capability by construction: the machine contract (`--json` schemas, `--heal`, exit-code taxonomy, `recovered[]` / `mutations[]` / `recoverable:false`) is the one agents already use. Three bindings, one verb: the engineer types `mm-harness launch ios`; the slot's prepare hook calls the same verb with slot context; dispatch scales it across the fleet. (Full contract: CLI-SPEC.md Part 6.)
+