@mmerterden/dev-toolkit-mcp 2.24.1

package/CHANGELOG.md

@@ -0,0 +1,708 @@
+# Changelog
+
+All notable changes to `@mmerterden/dev-toolkit-mcp` are documented here.
+
+Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); the project uses [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+Consumers pin minimum versions of this server (the multi-agent pipeline declares
+per-tool minimums), so version discipline matters here:
+
+- **Major** - a tool is removed or renamed, or an input schema stops accepting what it used to.
+- **Minor** - a new tool, or a new optional input on an existing tool.
+- **Patch** - fixes, docs, packaging, annotations, dependency bumps.
+
+Releases before this file exists are recorded in the git tags and commit history.
+
+---
+
+## 2.24.1
+
+### Added
+
+- Gate 13: Copilot CLI is now an exercised host, not a documented one. It was listed as
+  supported for months while the pipeline installer never registered this server there,
+  so every skill that reaches for a tool - `design-check`, the `ios_*` / `android_*`
+  simulator calls, the archive audits - had nothing to call on that host. The gate walks
+  the real round-trip: add, config landed, duplicate-add behaviour, remove.
+- The duplicate-add assertion pins a behavioural difference the installer depends on:
+  `codex mcp add` replaces an existing entry and exits 0, while `copilot mcp add`
+  refuses and exits 1 with `already exists`. Treating that exit code as a failure made a
+  correct registration report as "skipped MCP registration (Command failed)".
+
+## 2.24.0
+
+TestFlight pre-submission validation: ask Apple before Apple asks you.
+
+### Added
+
+- **`ios_testflight_validate`** - wraps `xcrun altool --validate-app`. This is the
+  authoritative pre-submission gate and it is complementary to, not a replacement
+  for, `ios_app_store_audit`. The static audit reads the archive on disk, so it
+  structurally cannot know whether the bundle ID is registered, whether the
+  embedded profile matches the App Store Connect app record, whether this
+  version+build pair was already used, or whether an entitlement is actually
+  provisioned for the App ID. Only Apple's server answers those.
+  Returned ITMS codes are mapped onto the App Store rule each one implies
+  (`ITMS-90683` → purpose strings / 5.1.1, `ITMS-91053` → privacy manifest
+  required-reason, `ITMS-90046` → entitlement not permitted by the profile, ...),
+  with Apple's own message passed through verbatim for anything unmapped rather
+  than guessed at.
+- **`ios_export_ipa`** - `.xcarchive` → signed `.ipa` via
+  `xcodebuild -exportArchive`, generating the `exportOptions.plist` from
+  arguments so callers do not hand-maintain one. A run that exits 0 without
+  producing an `.ipa` is reported as a failure, because xcodebuild does that.
+
+### Fixed
+
+- **`design_scenario_inventory` produced a different answer for the same input.**
+  Target discovery walks the filesystem and directory read order is not stable
+  across runs, and three things derived their order from it: the `byKind` /
+  `byCost` count maps (insertion order, so `JSON.stringify` differed), which
+  relaunch claimed a shared in-app rider (first match won), and the order riders
+  were listed within a batch. The release gate went red roughly one run in three
+  with no code change - the shape of defect that trains you to re-run instead of
+  to look. Count maps are now emitted with sorted keys, relaunch iteration is
+  canonical, and rider ids are sorted within each batch.
+- **Riders now ride with the relaunch that can actually drive their screen.**
+  Falling out of the fix above: two relaunch targets can match the same screen
+  while only one carries a launch argument, and the undrivable one could win the
+  riders purely by iterating first - yielding a plan that cannot be executed,
+  because the app never reaches the mock state those riders need. Assignment
+  scores an exact screen match above a substring one, then a relaunch with a
+  launch argument above one without, then canonical order. Substring pairing
+  ("Apis Form" ↔ "APIS") still works; it just no longer outranks an exact match.
+- New `plan-determinism.test.mjs` permutes `buildPlan`'s input across 40 seeds
+  and asserts the plan is byte-identical. A pass-count is not proof of order
+  independence: this property test caught residual rider-ordering drift on its
+  first run, after 44 consecutive green runs of the existing suite had missed it.
+- `scripts/gates.sh` no longer walks `.worktrees`. A git worktree is a separate
+  checkout of another branch, so its suites were being run against this tree and
+  gate 10c demanded that this tree's `npm test` name files that only exist on
+  another branch - a failure no change here could fix.
+
+### Notes
+
+- **Three-tier auth, and a skipped gate never reads as a pass.** Tier 1 is an App
+  Store Connect API key; tier 2 is an Apple ID plus an app-specific password,
+  which matters because creating an API key needs an Admin or App Manager role
+  that many developers on a corporate team do not have, while any Apple ID holder
+  can generate an app-specific password. With neither, the tool returns
+  `verdict: "SKIPPED"` and the reason. "Apple did not object" and "Apple was
+  never asked" must not render the same way.
+- **Secrets are referenced, never passed.** altool's `-p @keychain:<item>` and
+  `-p @env:<VAR>` indirections are the only forms used, so a password cannot
+  leak through the process list or through an error that echoes the command. A
+  unit test asserts no secret reaches argv.
+- **A literal password is refused, not used.** Passing one would put the secret in
+  argv; doing it silently would be worse, because the caller would get no signal
+  that their credential was exposed. The error names the two safe forms and the
+  one-off `altool --store-password-in-keychain-item` command that creates the
+  keychain item.
+- **A missing `password_env_var` is caught before altool sees it.** `-p @env:MISSING`
+  fails deep inside delivery with something that reads like a wrong password,
+  which sends you to rotate a credential that was fine.
+- **`-allowProvisioningUpdates` is off by default** on `ios_export_ipa`. That flag
+  lets xcodebuild register devices and create or modify provisioning profiles in
+  the developer account. A tool whose job is to check a build must not silently
+  alter the account the build belongs to, so it is opt-in via
+  `allow_provisioning_updates`.
+- Neither tool is in `READ_ONLY_TOOLS`: `ios_export_ipa` writes files and
+  `--validate-app` uploads the binary to Apple, so both require approval rather
+  than running unattended.
+- The generated `exportOptions.plist` temp dir is removed after a successful
+  export and kept (and reported) after a failure, so a failed run stays
+  inspectable without accumulating one temp dir per export forever.
+- Tool count 78 → 80 (iOS 35 → 37, Store Compliance 3 → 5).
+
+## 2.23.0
+
+Documentation that claimed more than it checked, and the gate that let it.
+
+**Editor support is now stated as verified vs compatible.** The README opened with
+"Works with Claude Code, Copilot CLI, Cursor, Antigravity, and VS Code Copilot Chat
+- the multi-agent-pipeline's full-orchestration targets". That parenthetical stopped
+being true in pipeline v10.7.0, when the Cursor / Antigravity / Codex / Copilot Chat
+adapters were deleted; the pipeline has targeted Claude Code and Copilot CLI only
+ever since.
+
+The list is not simply wrong, though: this is a plain stdio MCP server, so it does
+run in any MCP client, and the config snippets for those clients stay. What was
+wrong was presenting five hosts as supported when the gates exercise two. That
+distinction has a price tag now: 2.20.0 and 2.21.0 shipped an illegal `outputSchema`
+on the first tool, so Claude Code rejected the entire `tools/list` and served zero
+of the 78 - in the primary host, for two releases, with every gate green.
+
+**Gate 3b: per-family counts, not just the headline.** Gate 3 checked the two
+headline numbers and nothing else, so every subcount drifted behind a green check:
+
+| README said | reality |
+|---|---|
+| Device Control (42 tools) | 58 |
+| Store Compliance (4 tools) | 3 |
+| iOS Tools (34), diagram (31) | 35 |
+| 5 categories summing to 57 | 78 |
+
+The last row is the interesting one: the whole `design_*` family, six tools, was
+missing from the category list entirely, which is why the listed categories could
+never sum to the advertised total. A gate that verifies one number while its
+components drift reports an agreement it never checked.
+
+3b matches each `### <Family> Tools (N)` section against the served family count
+and requires the category bullets to sum to the total, so an unlisted family fails
+instead of hiding in the arithmetic. Verified by re-injecting a wrong subcount.
+
+All counts corrected, and the Design Audit category added.
+
+## 2.22.0
+
+**Fixes a server that Claude Code could not load at all.** `ios_list_devices`
+declared `outputSchema: { type: "array", items: {...} }`. MCP's `structuredContent`
+is an object, so the schema describing it must be `type: "object"`, and the host
+validates the ENTIRE `tools/list` response - so one illegal entry on the FIRST tool
+made all 78 unavailable:
+
+```
+Reconnected to dev-toolkit, but fetching tools failed:
+[{ code: invalid_value, path: [tools, 0, outputSchema, type],
+   message: Invalid input: expected "object" }]
+```
+
+`/mcp` showed `dev-toolkit - connected - tools fetch failed`: a connected server
+with zero usable tools. Any pipeline command depending on it (`design-check`,
+`test`, `build-optimize`) halted at its MCP gate.
+
+The declaration is removed rather than reshaped. Wrapping the payload as
+`{ devices: [...] }` would have made it legal, but this tool's text output is a
+JSON array that callers parse, so re-shaping it is a breaking change bought for
+structured output nobody requested. Dropping the schema restores a legal
+`tools/list` and leaves the text output byte-identical.
+
+**Why no gate caught it.** Gate 9 hand-wrote what it believed the spec allowed:
+
+```js
+if (t.outputSchema.type !== "object" && t.outputSchema.type !== "array")
+```
+
+It explicitly permitted `array`. The gate encoded a wrong belief about the spec and
+then verified the code against that belief, so the code and the gate agreed with
+each other and both disagreed with the client. Gate 9 is now object-only, and new
+**gate 9b** stops asserting beliefs altogether: it pipes the real `tools/list`
+response through `ListToolsResultSchema` from `@modelcontextprotocol/sdk` - the same
+Zod schema the host uses - so the check is authoritative rather than a guess.
+Verified by re-injecting the bad schema: 9b reproduces the host's error verbatim,
+down to the `path` array.
+
+## 2.21.0
+
+**Fixture-count noise is demoted, not reported as defects** (`docs/design-check-gaps.md`
+section 1, the item that dominated a real 109-target audit). A live capture is
+compared against a screen frame, and a screen frame carries whatever the mock
+fixture produced: 5 passenger rows in the design against 3 in the app makes every
+container height and every downstream position differ for a reason that is not a
+defect.
+
+`tools/design-check/content-cardinality.js` detects a repeated-group count
+difference from the element lists and demotes the geometry findings it explains.
+On by default; `content_cardinality: false` returns the raw findings.
+
+Written defensively, because the dangerous direction here is not noise but a
+HIDDEN DEFECT - demote too eagerly and the engine silently stops reporting real
+deviations, invisibly, in the one report whose job is to surface them. Five rules,
+each an explicit test:
+
+- nothing is ever DELETED; an affected finding stays with `advisory: true` plus a
+  shared `rootCause`, so it renders under the existing "DO NOT CHANGE" group, and
+  `contentCardinality.demoted` reports the count - a demotion is never silent;
+- only geometry findings are eligible. Copy, colour, typography, font-family,
+  tap-target and missing-element findings are never touched: a row-count
+  difference cannot make a colour wrong or a string mistranslated, so it can never
+  be the explanation for one;
+- an absent group is NOT a count difference. 1-vs-0 is a missing element, which is
+  a real defect and exactly what this must not explain away;
+- only findings AT OR BELOW the first differing group. A count difference shifts
+  what follows it, never what precedes it. A finding whose position cannot be
+  established keeps full severity - demoting on a guess is the failure mode this
+  module must not have;
+- idempotent: an already-advisory or `verified` finding is left byte-identical.
+
+The 21 tests cover both directions, with more weight on "must NOT demote" than on
+"must demote". 8 further tests assert the WIRING (the module is imported, the
+detector is called, the demotion is applied after copy comparison so it sees every
+finding, and the opt-out reaches it from the tool args) - a unit-tested module that
+nothing calls is the defect class the sibling pipeline repo just spent a release
+removing.
+
+**FIELD VALIDATION PENDING.** The gaps-doc acceptance criterion ("a screen whose
+fixture returns a different row count produces zero geometry findings") needs the
+real module, a live capture and Figma design context to confirm end to end. What
+is proven is the safe direction. Treat the tuning constants as provisional until a
+real run is measured, and check `contentCardinality.demoted` against the 52
+confirmed deviations that audit found before trusting a quieter report.
+
+## 2.20.0
+
+**`ios_app_store_audit` has tests.** The 18-rule App Store compliance scanner
+shipped 2,507 lines of rule code with none, while `npm test` ran only the
+design-check suite and gates step 10 globbed for `*.test.mjs`, found exactly one,
+and honestly reported "1 suite passed". An empty `__tests__/fixtures/` directory
+sat beside the rules as evidence that tests had been intended. This is the code
+that decides whether an archive is fit to upload, so a false PASS costs a
+rejection round.
+
+74 tests now cover the dispatcher contract (rule selection, `core` as a strict
+subset of `all`, an unknown rule id selecting nothing rather than falling back to
+the full scan, severity ordering, summary/verdict consistency, and the promise
+that one throwing rule cannot abort the scan) plus per-rule logic against
+synthetic contexts. Three properties are asserted across every rule, each
+protecting against a silent-miss shape the dispatcher permits:
+
+- a rule must return an ARRAY - `runAudit` does `if (Array.isArray(out))` and
+  otherwise discards the result while still listing the rule in `rulesRun`, so a
+  rule returning a bare object reports nothing and looks like a clean pass;
+- a rule must not throw on a sparse context (empty/null `infoPlist`, null
+  collections, no executable) - `runAudit` converts a throw into a "tool bug"
+  warning that REPLACES whatever that rule would have found;
+- every violation must carry the rule's own `ruleID`, or it is unattributable and
+  breaks the documented alphabetical-within-severity sort.
+
+**Gates 10b and 10c.** 10b requires every `tools/<dir>/` to carry at least one
+suite, so an untested tool directory is visible instead of being implied as
+covered. 10c requires `npm test` to name every suite on disk: Node 25 rejects
+`node --test tools/` (it resolves the directory as a module), so the script lists
+suites explicitly, and that list would otherwise go stale and hand a contributor
+a false green.
+
+**`android_set_locale` verifies instead of asserting.** It already read the locale
+back with `get-app-locales`, but reported the REQUESTED value as fact and put the
+device's answer in a parenthetical. A device that accepted the command and applied
+a different locale, or none, still read as success. It now compares them
+(case-insensitive, and accepting a more specific tag than asked for, so
+`tr` -> `tr-TR` is a match) and returns an error on mismatch.
+
+**Dependency audit is an allowlist, not a severity floor.** CI ran
+`npm audit --omit=dev --audit-level=high`. That was right about the two live
+findings and wrong as a policy: it ignores every moderate advisory forever,
+including unrelated future ones that could well be reachable here. The
+justification also lived only in a workflow comment, where nothing could
+invalidate it.
+
+`scripts/audit-allowlist.mjs` names each accepted advisory with its reason and
+re-verifies that reason on every run. The current exception is
+`@hono/node-server < 2.0.5` (GHSA-frvp-7c67-39w9), reached transitively through
+`@modelcontextprotocol/sdk`, which pins `^1.19.9`: a path traversal in
+`serve-static` on Windows. The reason it does not apply here is that this server
+is stdio-only, so the gate checks that no shipped source imports an HTTP
+transport, hono, or express - if someone adds a streamable-HTTP transport, the
+exception stops applying on that same run. There is no SDK release that lifts the
+pin (1.29.0 is the latest and still depends on `^1.19.9`), and
+`npm audit fix --force` would downgrade the SDK to 1.24.3. Anything unlisted now
+fails at any severity, an accepted advisory that escalates fails, and a stale
+entry whose advisory is gone fails too.
+
+**Stale rule count.** `index.js` and `context.js` said "17-rule" / "17 rules"
+while the registry held 18; the tool descriptor the model reads to choose
+`--rules` said 17 too. Corrected, and two tests now tie the descriptor's
+advertised full-scan and `core` counts to the rules that actually execute.
+
+## 2.19.0
+
+First three items off the design-check handoff spec (`docs/design-check-gaps.md`).
+
+**section 8 - `design_scenario_inventory` summary mode.** The full payload measured
+71,196 characters for a 109-target module and exceeded the host's tool-result cap
+on all seven runs of a real audit, forcing a write-to-file round trip every time.
+`summary: true` drops `targets[]`, which is nearly all of the bulk (label, screen,
+driver and a file+line+snippet evidence block per target). Nothing structural is
+lost: `plan[].targetIds` already carries every id in the order it should be driven
+and `groups[].ids` carries the per-screen lists, so a run can be driven entirely
+from the summary and ask for labels and evidence later. `targetsOmitted` and
+`summary: true` are stated explicitly, so a consumer can tell a withheld list from
+a scan that found nothing. Measured on the real module's shape at its reported
+target count: 66,591 characters down to 450.
+
+**section 9, second half - `ios_screenshot` gains `path`.** Returning a base64 PNG
+per capture exhausts the caller's context across the 100+ captures an audit takes,
+which is why the motivating run shelled out to `xcrun simctl io` directly. With
+`path` the file is written and only its location comes back. A missing parent
+directory is an error rather than a silent miss.
+
+**section 9, first half - the AX-box caveat is now on the tool.**
+`design_ui_geometry` returns accessibility boxes, glyph runs and hit areas, not
+layout containers, so a 247pt design text container measured against its 78pt glyph
+box produces phantom findings. The description says so and points at measuring from
+the pixels instead. Documented rather than changed: returning container-union boxes
+is a real option but it changes what every existing caller receives.
+
+Still open from the spec: sections 1, 2, 2a, 3, 4, 5, 6, 6a (component-variant
+comparison, variant previews, per-finding fileKey, typography/colour/copy
+expectations, code location and token snapping) and section 7 (scroll-stitch).
+
+## 2.18.0
+
+**A tool name with a valid family prefix but no matching case reported success.**
+Every handler's `default:` arm returns null, and `dispatchStep` / the CallTool
+handler only threw "Unknown tool" for a name matching no prefix at all. So
+`ios_taap`, `design_reprot`, `android_tpa` reached their handler, came back
+null, and were answered to the host as the literal text `"null"` with no
+`isError`. Inside `agent_run_steps` the step was recorded `status: "ok"` and the
+verdict stayed `all_ok`. Same false-success class as the 2.13.0 batch fix, in a
+different place. A null return is now an error at both levels.
+
+**outputSchema + structuredContent (spec 2026-07-28).** Nine tools declare an
+output schema and fill `structuredContent` alongside their existing text
+content: the two accessibility audits, the archive and APK audits,
+`ios_list_devices`, `ios_visual_diff`, `android_launch_time`,
+`design_ui_geometry` and `agent_run_steps`. Only shapes read off the return
+statement are declared - `ios_xcresult` (four shapes by mode),
+`ios_app_store_audit`, the delegated `design_*` reports and `web_eval` are
+deliberately left out, because a schema that does not match its payload makes
+the host reject a good result. Text content is unchanged, so a host that
+ignores `structuredContent` sees no difference.
+
+**Two new gates.** Gate 8 drives three unknown names through the call and batch
+paths and requires an error on each. Gate 9 requires every tool advertising an
+outputSchema to actually return `structuredContent`, and to keep its text
+content beside it. 14 gates, all green.
+
+## [2.17.0] - 2026-07-26
+
+The audit measured geometry only, so it could not answer whether the copy was
+right — and a perceptual diff reporting "these pixels differ" is not an answer.
+
+### Added
+
+- **`compareCopy` — copy checked against the design's UX-WRITING ANNOTATION.** The
+  authoritative strings are the annotation on the Figma node, not the frame render,
+  which is a stale picture of the words. An exact live match is reported as
+  verified (so the report shows what was checked, not only what failed), a near
+  miss as a copy defect carrying both strings, and a string with no counterpart as
+  advisory, because the capture may not show the state that carries it.
+
+  Matching is one-to-one: without claiming, a single live label is offered as the
+  near match for several unrelated design strings and a loose threshold turns "not
+  on this screen" into a fabricated defect. Exact matches claim first, then near
+  matches take what remains, strongest pair first.
+
+  Reachable from `design_visual_compare` via `design_copy`, so one call covers
+  geometry and copy together.
+
+Found on the audited module the first time it ran: the design specifies "Soyadı",
+the app renders "Soyad" — with 10 of 13 strings confirmed on-spec.
+
+## [2.16.0] - 2026-07-26
+
+A stretching element's horizontal insets were measured against the frame, which
+reported a perfectly on-spec button as off.
+
+### Fixed
+
+- **Horizontal insets are measured against the parent, not the frame.** A button
+  16pt inside a modal keeps 16pt on any device, but its distance to the frame edge
+  changes with both the screen width and the modal's own width. Measured against
+  the frame, design 32pt vs live 40pt looked like a defect; against the parent both
+  sides read 16/16 — identical. Parenthood is recovered geometrically (the smallest
+  box that fully contains this one), so it needs no project knowledge and applies
+  to either side. A genuinely wrong inset inside a parent is still reported.
+
+### Changed
+
+- **Advisories collapse to one line.** They exist to say "do not act on this", so
+  a full card per advisory beside the real findings doubled the page for the same
+  elements while giving the reader nothing to do. Now a single expandable summary.
+
+## [2.15.0] - 2026-07-26
+
+The checks added in 2.12–2.14 overlapped, so one defect could arrive in the
+report three times and a finding the engine could not actually confirm was
+presented with the same weight as one it could.
+
+### Changed
+
+- **One measurement, one owner.** `edge` was reporting distances that `inset` and
+  `gap` already owned — including, via the raw spec geometry, the very
+  wrapper-vs-visible phantom 2.11.0 removed. It is now restricted to the one
+  thing nothing else measures: the horizontal distance between two siblings (an
+  icon-to-label gap). Vertical sibling distances belong to `gap`, horizontal
+  frame distances to `inset`, which resolves them from the pixels.
+- **Centring and symmetry read the pixel edges too.** They were computed from the
+  raw boxes, so a full-bleed wrapper was trivially "centred" while the live AX
+  union was not — an off-centre finding on a correct screen. The pixel edges are
+  now resolved once per element and every check reads the same answer.
+- **Unconfirmed findings are advisory.** An inset with no pixel confirmation may
+  be comparing a wrapper box against a glyph run, so it is reported with that
+  reason attached rather than as a defect. Alignment findings derived from the
+  same boxes follow it.
+
+Re-measuring an existing 28-screen audit: 109 reported deviations became 52
+confirmed ones, and the worst offender went from 7 findings to 1.
+
+## [2.14.0] - 2026-07-26
+
+Design conformance was measured with absolute positions, which answer the wrong
+question: two screens showing the same component with different mock content put
+it at different Y, so a conformant screen was reported as "+37pt off" while a
+real defect beside it went unreported.
+
+### Added
+
+- **Local edge distances — the on-device-inspector measurement, made generic.**
+  For every element, the four distances to whatever actually bounds it: the
+  nearest sibling overlapping on the perpendicular axis, else the frame edge.
+  The identical pure-geometry function runs over the design box list and the live
+  box list, so no per-project knowledge and nothing that has to execute inside
+  the app. A block pushed down by a taller fixture keeps its own distances and
+  stays silent; a padding or gap that genuinely changed surfaces on the exact
+  edge, naming what it was measured against.
+
+  Three cases are demoted to advisory rather than reported as defects, because
+  each is the same fact arriving twice or a quantity that is not local:
+  - a trailing edge that moved only because the element itself grew (already
+    reported as size),
+  - a distance measured to a sibling on one side and to the frame on the other,
+  - a vertical distance to the frame, which accumulates every block above it and
+    so has exactly the flaw absolute Y had. Horizontal frame distances are real
+    margins and stay real.
+
+### Notes
+
+- Font size, weight and colour still cannot be read from outside the process, so
+  typography remains a design-side expectation to verify in code rather than a
+  measured delta.
+
+## [2.13.0] - 2026-07-26
+
+`agent_run_steps` reported failed steps as successes. A batch could run to
+completion with `verdict: "all_ok"` while every step in it had failed.
+
+### Fixed
+
+- **Step failures are now reported as failures.** `run()` signals a command
+  failure by RETURNING a string prefixed with `ERROR: ` rather than by throwing.
+  The `tools/call` handler tests for that marker with `isFailure()` before
+  answering the host, but the batch loop only had a `try`/`catch`, so a broken
+  step was recorded `status: "ok"`, `errors` stayed `0`, the verdict published
+  `all_ok`, and `stop_on_first_error` never fired because nothing threw. The loop
+  now applies the same `isFailure()` judgement the single-call path does.
+- **`stop_on_first_error` stops the batch.** Previously only a thrown exception
+  could halt it, which meant the common case (a CLI exiting non-zero) ran every
+  remaining step against a device left in an unexpected state.
+
+### Added
+
+- **`aborted` in the batch report**, distinguishing "stopped early because a step
+  failed" from "ran everything and some steps failed". An aborted batch also sets
+  `isError` on the result envelope; failures the caller opted into with
+  `continue_on_error` do not, since there the call did what it was asked.
+- **`design_*` steps are dispatched.** The tool description offered "any tool
+  name" while the loop only handled `ios_*`, `android_*` and `web_*`, so the six
+  design-check tools were refused with "Unknown tool".
+- **Gate 7 in `scripts/gates.sh`** covers all of the above, probing with
+  `ios_archive_audit` on a missing path: it returns the failure marker without
+  throwing and needs no simulator, emulator or external binary, so it exercises
+  the same path on every runner. Verified to fail against the old behaviour.
+- **Gate 9 in `scripts/gates.sh`** requires a CHANGELOG entry for the version in
+  `package.json`. Added because 2.11.0 and 2.12.0 shipped without one.
+
+### Changed
+
+- The `agent_run_steps` description and its `tool` schema text now state the
+  accepted prefixes and the failure semantics instead of "any tool name".
+- Nested `agent_*` steps are refused explicitly rather than falling through to
+  "Unknown tool"; a batch able to nest itself has no recursion bound.
+
+---
+
+## [2.12.0] - 2026-07-26
+
+Recorded after the fact: this release shipped without a CHANGELOG entry. Summary
+transcribed from commit `a8d83ba`.
+
+`design_visual_compare` answers "is it built 1:1" with relations rather than
+absolute positions.
+
+### Changed
+
+- **Absolute Y was the wrong unit.** Two screens rendering the same component
+  with different mock content place it at a different Y, so the audit flagged
+  conformant screens as "+37pt off" while missing an actual defect beside it.
+  Absolute top offset is demoted to advisory; the sibling gap plus the relational
+  checks carry the vertical signal.
+
+### Added
+
+- Content-independent checks promoted to first class: centred-in-frame (offset
+  from centre, not position), margin symmetry, shared centre line, and
+  icon/control size, which also flags anything under the 44pt minimum tap target.
+- 7 tests (80 total).
+
+---
+
+## [2.11.0] - 2026-07-25
+
+Recorded after the fact: this release shipped without a CHANGELOG entry. Summary
+transcribed from commit `0ec8ba3`.
+
+### Fixed
+
+- **False-positive inset findings.** A Figma node tree reports the instance
+  wrapper (full-bleed, x=0, w=375) while the accessibility tree reports the
+  visible card inside it (inset 16pt), so comparing one against the other
+  reported "+16pt off" on a conformant screen. For a row spanning at least 80% of
+  the frame the insets are now read off the two renders instead. Verified on a
+  real screen: 7 deviations down to 3, all 3 genuine. A genuinely wrong inset is
+  still caught, with a regression test.
+- An advisory-only screen no longer prints an empty DEVIATIONS heading, and that
+  guard's assertion targets the status chip rather than matching a substring
+  anywhere in the document.
+
+### Added
+
+- **Fixed-field fix prompt** replacing prose that lost which property moved and
+  by how much: element | property | expected -> actual | delta, plus a SHARED
+  ROOT CAUSE section collapsing a delta repeated across elements into one likely
+  container or token cause, and a DO NOT CHANGE section so advisories and fixture
+  differences are not "fixed" into new bugs.
+- 6 tests (73 total).
+
+---
+
+## [2.10.0] - 2026-07-25
+
+`design_visual_compare` now measures what a designer actually specifies, in
+points, instead of comparing raw pixel dimensions between two frames that are
+rarely the same size.
+
+### Changed
+
+- **Responsive, point-based conformance measurement.** Raw width/height deltas
+  were misleading: a device and a Figma frame are seldom the same width (402pt
+  vs 375pt), so a full-bleed 375pt design container measured against a 402pt
+  screen's 16pt-inset card reported "-29px too narrow" when nothing was wrong,
+  and any container that hugs its content turned every fixture difference into a
+  size finding that buried the real defects. The comparison now reports
+  per-element edge insets (left/right) rather than raw width, gaps between
+  consecutive elements, vertical placement, and font size, family and text
+  colour sampled from the text ink rather than the box average -  the box average
+  previously returned the background colour and so passed every check. Pass
+  `responsive: false` to restore the previous absolute-delta behaviour.
+- **Height is advisory.** It is still reported, but a content-driven height
+  difference no longer decides pass/fail and no longer inflates the deviation
+  count. Advisories render in their own uncounted group in the report.
+
+### Fixed
+
+- **The report dropped the measured delta.** `findingLine` discarded `f.detail`
+  whenever `expected`/`actual` were present, so an inset finding rendered as
+  "left 0pt -> left 16pt" and lost both the delta and which edge moved. The
+  detail is the actionable half of a responsive measurement, so it now renders
+  alongside.
+- **An advisory-only screen contradicted its own header.** The header total
+  excluded advisories but the per-screen status label and `fail` class were
+  computed by a separate expression that still counted them, so a screen whose
+  only finding was advisory rendered as DEVIATION underneath a header that said
+  0 deviations. Both now exclude advisories on the same terms.
+
+Adds 13 tests pinning the inset/gap/advisory behaviour and the report's
+advisory accounting.
+
+## [2.9.0] - 2026-07-25
+
+Every item below is one shape of defect: a tool that reported success while
+doing nothing. Three wrapped host-tool flags had silently stopped existing, and
+because no failure ever carried `isError`, no host could tell.
+
+### Fixed
+
+- **`isError` on every failure.** The `CallTool` dispatch returned command
+  failures as ordinary text, so a host -  and the pipeline gates reading these
+  results -  saw failure as success. Failures now return `isError: true`. Failing
+  command output is also capped at 600 chars: a failed `simctl` call was
+  inlining its entire ~3 KB usage page into the caller's context.
+- **`ios_biometric` was a no-op that claimed success.** `simctl keychain
+  <device> biometric-enroll` / `biometric-match` do not exist -  `keychain`
+  supports only `add-root-cert`, `add-cert`, `reset`. Now drives the BiometricKit
+  notification via `notifyutil` inside the simulator, and because `notifyutil`
+  exits 0 even when it cannot post the name, its output is inspected: a "Failed
+  with code N" line is reported as a failure with next steps instead of
+  "success simulated".
+- **`ios_go_home` was a no-op.** `simctl io <device> pressButton` does not exist
+  -  `io` supports only `enumerate`, `poll`, `recordVideo`, `screenshot`,
+  `screenConfig`. Routed through `idb ui button HOME`, like tap/swipe/type.
+- **`android_set_locale` reported success unconditionally.** It broadcast the
+  dead pre-Android-7 `SET_LOCALE` intent with stderr sent to `/dev/null`, and
+  `am broadcast` exits 0 even when nothing handles the intent. Now uses the
+  supported per-app path `cmd locale set-app-locales` (API 33+), inspects the
+  output for `Unknown command` / usage text before claiming success, and reads
+  the value back. `package_name` stays optional in the schema (no breaking
+  change) but the call returns an error instead of doing nothing without it.
+- **Command injection.** Commands are built as strings for a shell, and `$( )`
+  expands inside double quotes, so double-quoting a caller value did not contain
+  it. `ios_revoke_permission`'s `service` and the Android `permission` names were
+  interpolated with no quoting at all. Adds `shq()` (POSIX single-quoting),
+  `num()` for coordinates and scales, and `token()` for enum-shaped values, and
+  applies them across every caller-supplied interpolation.
+- **Unavailable-capability guards** ("Xcode not installed", "Android SDK not
+  installed") returned as success text; they are failures and now say so.
+- **ITMS-91061 filed at the wrong severity.** A required-SDK framework missing
+  `PrivacyInfo.xcprivacy` was a `5.1.1` WARNING; it has been an enforced upload
+  rejection since 2025-02-12. Now `ITMS-91061` at ERROR. This changes
+  archive-guard verdicts: archives that previously passed with a warning fail now.
+
+### Added
+
+- **`sdk-floor` audit rule** (ITMS-90725), bringing `ios_app_store_audit` to
+  **18 rules**. Asserts `DTSDKName` / `DTPlatformVersion` major >= 26 and
+  `DTXcode` >= 2600, the iOS 26 / Xcode 26 floor in force since 2026-04-28 -  a
+  hard upload rejection that nothing checked. Grouped as `core` because it costs
+  nothing to run. Reports a WARNING when an archive carries no build receipts at
+  all, rather than passing silently.
+
+### Changed
+
+- **`peerDependencies.playwright`** from the exact pin `1.61.1` to
+  `>=1.60.0 <2`. Since npm 7 an unsatisfiable peer is a hard `ERESOLVE`, so the
+  exact pin broke installs for anyone already on 1.62.0. None of the APIs removed
+  in the 1.60 window are used here, and browser-binary coupling is already
+  enforced inside the playwright package itself.
+- **`engines.node`** from `>=18.0.0` to `>=20.0.0`, matching what
+  `playwright@1.62.0` requires and what CI already runs.
+
+## [2.7.1] - 2026-07-25
+
+### Added
+
+- **Tool annotations** on all 78 tools (MCP `2025-11-25`): `readOnlyHint`,
+  `destructiveHint`, `idempotentHint`, `openWorldHint`. Hosts use these for
+  permission prompts and for deciding what may run unattended. 24 tools are
+  read-only (screenshots, UI trees, audits, device/app listings), 5 are
+  destructive (`ios_erase_device`, `ios_keychain_reset`, `ios_reset_permissions`,
+  `android_uninstall_app`, `android_clear_app_data`), 8 are open-world (the
+  `web_*` family). The classification lives in one auditable block in
+  `index.js`, not inline on 78 literals.
+- **`scripts/gates.sh`** - the single definition of "safe to ship": syntax over
+  every loaded file, a stdio `tools/list` handshake that must answer with a
+  non-zero count, the tool count matching every place it is advertised
+  (`package.json` description + README header), `npm pack --dry-run` covering
+  every runtime `tools/*/` directory, stdout hygiene (stdout is the JSON-RPC
+  channel), version single-sourcing, and every test suite in the repo. Run with
+  `npm run gates`.
+- **CI** (`.github/workflows/ci.yml`) on ubuntu + macOS x Node 20/22, running
+  `npm run gates` so the release path and CI cannot drift apart.
+- **`npm run gates`** script.
+
+### Changed
+
+- `@modelcontextprotocol/sdk` range `^1.0.0` -> `^1.29.0`. The old range let a
+  four-major spread install under the same declaration; the tested version is
+  now the declared one. Transitive advisories dropped from 8 (2 high: `hono`,
+  `fast-uri`) to 2 moderate.
+- `serverInfo.version` is read from `package.json` instead of a second
+  hardcoded literal, so a version bump can no longer leave the server
+  advertising a version consumers gate on but never received.
+
+### Known
+
+- Two moderate advisories remain in `@hono/node-server`, pulled in by the SDK's
+  streamable-HTTP transport. This server only runs over stdio and never loads
+  that path; the fix has to land upstream in the SDK (npm's only local
+  "fix" is a downgrade to an older SDK, which would be a regression).