@topy-ai/maggie 0.7.23 → 0.7.24

package/README.md

@@ -87,7 +87,9 @@ maggie qa assertion-audit --project . \
 
 For a dialog or drawer, include a browser-runtime `scroll-owner-count` check
 with `expected: 1`. This catches the fixed-shell plus inner-content double
-scrollbar that static class checks can miss.
+scrollbar that static class checks can miss. For icon controls, use
+`icon-rendered` with a visible glyph, positive width/height, and an accessible
+label; this catches a missing runtime glyph that build/typecheck cannot see.
 
 Dashboard and documentation audits are provider-neutral and keep host data
 behind explicit evidence files:
@@ -214,7 +216,7 @@ maggie memory ...                # confirmed preferences and lessons
 maggie feedback ...              # redact, preview, submit, list
 maggie qa ...                    # scenario browser QA, fix/retest, release gate
 maggie localization ...          # plan, validate, review, publish, stale
-maggie service ...               # import, sync/report, catalogue, lifecycle, validate
+maggie service ...                # import, sync/report, catalogue, lifecycle, validate
 maggie seo performance ...       # sampled PageSpeed/CWV report and baseline
 maggie seo images ...             # inventory, variants, confirmation, validate
 maggie seo sitemap ...            # typed/semantic plan, agent-files, apply, rollback
@@ -224,6 +226,7 @@ maggie seo head-tags ...          # rendered-shell head metadata drift audit
 maggie ops favicon-check ...      # served favicon behaviour check
 maggie deployment | migration | release | analytics | schedule
 maggie deployment readiness --project PATH
+maggie deployment parity --project PATH --evidence FILE --output FILE
 maggie migration identity --identity-file FILE [--expected-file FILE]
 maggie deployment canary --asset URL=SHA256 --render-report report.json
 maggie design icon-inventory --source-dir src --runtime assets/icons.css
@@ -298,6 +301,11 @@ maggie design icon-inventory --project . --source-dir src \
   --runtime public/assets/icons.css --output docs/icon-inventory.json
 ```
 
+The inventory covers compound selectors such as `.ph.ph-arrow-square-out`
+and is only static name coverage. Pair changed icon controls with a
+browser-runtime `icon-rendered` assertion so the host adapter proves that the
+glyph is visible, has positive dimensions, and has an accessible label.
+
 After deployment, compare an immutable asset fingerprint and validate the
 browser adapter's rendered report:
 
@@ -312,8 +320,23 @@ The canary report requires a screenshot and zero console errors, missing
 assets, and visual placeholders for every route. It records safe cache headers
 only and never stores response bodies, cookies, or credentials.
 
+When workers, migrations, browser drivers, import jobs, or route APIs are part
+of the deployment, validate their sanitized parity evidence before the canary:
+
+```bash
+maggie deployment parity --project . \
+  --evidence .maggie/verification/runtime-parity-input.json \
+  --output .maggie/verification/runtime-parity.json
+```
+
+The parity contract checks required worker configuration, migration
+privileges, route API status, stale resident processes, source-job IDs, and
+browser/driver compatibility. Add the resulting report to readiness with
+`--runtime-parity`; a failed report blocks the gate.
+
 Unit regression does not establish runtime release readiness. Produce unit
-evidence and then validate all five release evidence slots:
+evidence and then validate all required release evidence slots; add
+`--runtime-parity` when the deployment uses the worker/browser surfaces above:
 
 ```bash
 python3 tools/tests/run_regression.py \
@@ -323,13 +346,27 @@ maggie deployment readiness --project . \
   --browser-report .maggie/verification/browser-evidence.json \
   --rendered-canary .maggie/deployment-canary.json \
   --deployment-preflight .maggie/release-preflight.json \
+  --runtime-parity .maggie/verification/runtime-parity.json \
   --output .maggie/deployment-readiness.json
 ```
 
 The readiness report follows `maggie-deployment-readiness.v1`. It reports unit
 regression, package smoke, host browser evidence, rendered canary, and
 deployment preflight separately. Missing host adapter evidence is
-`inconclusive`; only five passing slots produce `passed`.
+`inconclusive`; only all configured slots produce `passed`.
+
+For service-booking hosts, validate independent import, local-search, and
+website-research jobs before public generation:
+
+```bash
+maggie service orchestration-validate --project . \
+  --manifest .maggie/booking/onboarding-orchestration.json \
+  --output docs/service-onboarding-orchestration.json
+```
+
+The contract requires unique idempotency keys, bounded retry history, pollable
+status references, and disjoint field ownership so one onboarding workflow
+cannot overwrite another.
 
 ### Localization and analytics release gates
 
@@ -356,8 +393,8 @@ artifact schemas.
 Recommended upgrade sequence for the current release:
 
 ```bash
-npx @topy-ai/maggie@0.7.23 update --project . --force
-npx @topy-ai/maggie@0.7.23 cleanup --project .
+npx @topy-ai/maggie@0.7.24 update --project . --force
+npx @topy-ai/maggie@0.7.24 cleanup --project .
 ```
 
 Maintainers should pass npm credentials through the repository helper, never
@@ -367,7 +404,9 @@ as a command-line argument:
 node scripts/publish-npm.mjs --maggie-env-file ../.env
 ```
 
-The 0.7.23 workflow adds the single-scroll-owner MaggieDash modal primitive,
+The 0.7.24 workflow adds browser-runtime `icon-rendered` assertions, sanitized
+worker/browser parity preflight evidence, and the provider-neutral asynchronous
+service-onboarding contract. The 0.7.23 workflow adds the single-scroll-owner MaggieDash modal primitive,
 server-runtime-only auth/provider configuration guidance, best-effort optional
 identity-mirror semantics, and `scroll-owner-count` browser QA evidence. The
 0.7.22 workflow adds provider-catalogue authority checks, field/variant

package/README.zh-TW.md

@@ -8,7 +8,7 @@ Codex、Claude Code 與相容的 coding agents。
 ## 安裝
 
 ```bash
-npx @topy-ai/maggie@0.7.23 init --agent all
+npx @topy-ai/maggie@0.7.24 init --agent all
 npx @topy-ai/maggie doctor --project .
 ```
 
@@ -25,6 +25,8 @@ maggie doctor --project . --require-bootstrap --strict
 deployment、memory、feedback 和 MaggieDash。內容先 draft/review，外部寫入、
 publish 與 production deployment 需要明確確認。
 
+0.7.24 加入 `icon-rendered` browser QA assertion、worker/browser deployment parity
+preflight，以及 import/search/research 的非同步 service onboarding contract。
 0.7.23 加入 dashboard dialog 單一 scroll owner、server runtime-only auth/provider
 設定規則、optional identity mirror 的 best-effort 邊界，以及 QA 的
 `scroll-owner-count` browser evidence。0.7.22 加入 provider catalogue authority check、field/variant sync report、

package/bin/maggie.js

@@ -108,10 +108,12 @@ Usage:
   maggie service validate --project PATH
   maggie service inspect --project PATH
   maggie service status --project PATH
+  maggie service orchestration-validate --project PATH --manifest FILE
   maggie service convert-page <page-path> --project PATH
   maggie service match-pages --project PATH --pages-dir src/pages
   maggie deployment --project PATH --target vps-with-cloudflare-dns
   maggie deployment readiness --project PATH
+  maggie deployment parity --project PATH --evidence FILE --output FILE
   maggie deployment canary --project PATH --asset URL=SHA256 --render-report report.json --output docs/deployment-canary.json
   maggie migration --project PATH --environment staging
   maggie migration identity --identity-file FILE [--expected-file FILE]
@@ -301,7 +303,8 @@ function marketplace(args) {
 
 function service(args) {
   const root = projectRoot(args);
-  const script = join(root, "tools", "clis", "maggie_service_booking.py");
+  const scriptName = args[0] === "orchestration-validate" ? "maggie_service_onboarding.py" : "maggie_service_booking.py";
+  const script = join(root, "tools", "clis", scriptName);
   if (!existsSync(script)) throw new Error(`service booking CLI is missing: ${script}`);
   const result = spawnSync("python3", [script, ...args], { stdio: "inherit", cwd: root, env: { ...process.env, MAGGIE_VERSION: PACKAGE_VERSION } });
   if (result.error) throw result.error;
@@ -413,6 +416,7 @@ try {
   else if (command === "ops") workflowCli("maggie_ops.py", args);
   else if (command === "deployment" && args[0] === "canary") workflowCli("maggie_deployment_canary.py", args.slice(1));
   else if (command === "deployment" && args[0] === "readiness") workflowCli("maggie_deployment_readiness.py", args.slice(1));
+  else if (command === "deployment" && args[0] === "parity") workflowCli("maggie_deployment_parity.py", args.slice(1));
   else if (command === "deployment") workflowCli("maggie_deployment.py", args);
   else if (command === "migration") workflowCli("maggie_migration.py", args);
   else if (command === "schedule") workflowCli("maggie_schedule.py", args);

package/bundled-contracts/maggie-deployment/readiness-v1.schema.json

@@ -16,7 +16,8 @@
         "packageSmoke": {"$ref": "#/$defs/check"},
         "browserEvidence": {"$ref": "#/$defs/check"},
         "renderedCanary": {"$ref": "#/$defs/check"},
-        "deploymentPreflight": {"$ref": "#/$defs/check"}
+        "deploymentPreflight": {"$ref": "#/$defs/check"},
+        "runtimeParity": {"$ref": "#/$defs/check"}
       }
     }
   },

package/bundled-contracts/maggie-deployment/runtime-parity-v1.schema.json

@@ -0,0 +1,38 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://maggie.noblox.app/contracts/deployment-runtime-parity-v1.json",
+  "title": "Maggie deployment worker and browser runtime parity evidence",
+  "type": "object",
+  "required": ["schemaVersion", "environment", "passed", "worker", "browser"],
+  "properties": {
+    "schemaVersion": {"const": "maggie-deployment-runtime-parity.v1"},
+    "environment": {"enum": ["development", "staging", "production"]},
+    "passed": {"const": true},
+    "worker": {
+      "type": "object",
+      "required": ["config", "migration", "routeApis", "residentProcesses", "sourceJobs"],
+      "properties": {
+        "config": {"$ref": "#/$defs/config"},
+        "migration": {"type": "object", "required": ["privilegeCheck"], "properties": {"privilegeCheck": {"$ref": "#/$defs/passed"}}},
+        "routeApis": {"type": "array", "minItems": 1, "items": {"$ref": "#/$defs/route"}},
+        "residentProcesses": {"$ref": "#/$defs/processes"},
+        "sourceJobs": {"type": "array", "items": {"$ref": "#/$defs/job"}}
+      },
+      "additionalProperties": true
+    },
+    "browser": {
+      "type": "object",
+      "required": ["browserVersion", "driverVersion", "compatible"],
+      "properties": {"browserVersion": {"type": "string", "minLength": 1}, "driverVersion": {"type": "string", "minLength": 1}, "compatible": {"const": true}},
+      "additionalProperties": true
+    }
+  },
+  "$defs": {
+    "passed": {"type": "object", "required": ["passed"], "properties": {"passed": {"const": true}}, "additionalProperties": true},
+    "config": {"type": "object", "required": ["required", "missing", "passed"], "properties": {"required": {"type": "array", "minItems": 1, "items": {"type": "string", "minLength": 1}}, "missing": {"type": "array", "maxItems": 0}, "passed": {"const": true}}, "additionalProperties": true},
+    "route": {"type": "object", "required": ["method", "path", "status", "passed"], "properties": {"method": {"type": "string"}, "path": {"type": "string", "pattern": "^/"}, "status": {"type": "integer", "minimum": 200, "maximum": 399}, "passed": {"const": true}}, "additionalProperties": true},
+    "processes": {"type": "object", "required": ["checked", "unexpected", "stale", "passed"], "properties": {"checked": {"const": true}, "unexpected": {"type": "array", "maxItems": 0}, "stale": {"type": "array", "maxItems": 0}, "passed": {"const": true}}, "additionalProperties": true},
+    "job": {"type": "object", "required": ["jobId", "passed"], "properties": {"jobId": {"type": "string", "minLength": 1}, "passed": {"const": true}}, "additionalProperties": true}
+  },
+  "additionalProperties": true
+}

package/bundled-contracts/maggie-service-booking/onboarding-orchestration-v1.schema.json

@@ -0,0 +1,34 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://maggie.noblox.app/contracts/service-onboarding-orchestration-v1.json",
+  "title": "Maggie provider-neutral asynchronous service onboarding orchestration",
+  "type": "object",
+  "required": ["schemaVersion", "workflows", "fieldOwnership"],
+  "properties": {
+    "schemaVersion": {"const": "maggie-service-onboarding-orchestration.v1"},
+    "workflows": {"type": "array", "minItems": 3, "maxItems": 3, "items": {"$ref": "#/$defs/workflow"}},
+    "fieldOwnership": {"type": "object", "minProperties": 1, "additionalProperties": {"enum": ["import", "search", "research"]}}
+  },
+  "$defs": {
+    "workflow": {
+      "type": "object",
+      "required": ["name", "jobId", "idempotencyKey", "state", "history", "attempt", "maxAttempts", "owner", "statusRef", "nextAction", "writes"],
+      "properties": {
+        "name": {"enum": ["import", "search", "research"]},
+        "jobId": {"type": "string", "minLength": 1},
+        "idempotencyKey": {"type": "string", "minLength": 1},
+        "state": {"enum": ["queued", "running", "succeeded", "failed", "blocked", "cancelled"]},
+        "history": {"type": "array", "minItems": 1, "items": {"type": "object", "required": ["state", "at"], "properties": {"state": {"type": "string"}, "at": {"type": "string"}}}},
+        "attempt": {"type": "integer", "minimum": 1},
+        "maxAttempts": {"type": "integer", "minimum": 1},
+        "owner": {"type": "string", "minLength": 1},
+        "statusRef": {"type": "string", "minLength": 1},
+        "nextAction": {"type": "string", "minLength": 1},
+        "writes": {"type": "array", "minItems": 1, "items": {"type": "string", "minLength": 1}},
+        "errorCode": {"type": ["string", "null"]}
+      },
+      "additionalProperties": true
+    }
+  },
+  "additionalProperties": true
+}

package/bundled-skills/maggie-deployment/SKILL.md

@@ -2,7 +2,7 @@
 name: maggie-deployment
 description: Deploy and operate Maggie blog projects with Cloudflare Workers as the default target, while preserving an adapter boundary for VPS, GCP, and AWS.
 metadata:
-  version: 1.3.0
+  version: 1.4.0
 ---
 
 # Maggie Deployment
@@ -37,12 +37,33 @@ visitor-facing files. The canary must include screenshots, zero console or
 network errors, and zero placeholder matches. Query-driven routes belong in
 behavior/API checks, not static byte baselines.
 
+## Worker/browser runtime parity
+
+Before a canary when the release depends on workers, migrations, browser
+automation, import jobs, or route APIs, collect sanitized host-adapter evidence
+and validate it before traffic moves:
+
+```bash
+maggie deployment parity --project . \
+  --evidence .maggie/verification/runtime-parity-input.json \
+  --output .maggie/verification/runtime-parity.json
+```
+
+The `maggie-deployment-runtime-parity.v1` contract checks required worker
+configuration and missing bindings, migration privileges, route API status,
+stale/unexpected resident import processes, non-empty source-job IDs, and
+browser/driver compatibility. It is provider-neutral: the host adapter runs
+the environment checks and supplies only safe facts; Maggie validates the
+evidence and never receives credentials, cookies, or response bodies. A failed
+parity report blocks the readiness command and therefore the canary.
+
 ## Release readiness evidence
 
 Unit regression is necessary but does not prove runtime release readiness. The
-readiness command keeps five evidence slots separate: dependency-free unit
-regression, package smoke, host browser evidence, rendered canary, and
-deployment preflight:
+readiness command keeps five required evidence slots separate: dependency-free
+unit regression, package smoke, host browser evidence, rendered canary, and
+deployment preflight. Add the optional `runtimeParity` slot whenever the
+release uses the worker/browser surfaces described above:
 
 ```bash
 python3 tools/tests/run_regression.py \
@@ -52,12 +73,13 @@ maggie deployment readiness --project . \
   --browser-report .maggie/verification/browser-evidence.json \
   --rendered-canary .maggie/deployment-canary.json \
   --deployment-preflight .maggie/release-preflight.json \
+  --runtime-parity .maggie/verification/runtime-parity.json \
   --output .maggie/deployment-readiness.json
 ```
 
 The report follows `maggie-deployment-readiness.v1`. A failed evidence file
 returns `failed`; a missing or unavailable host/browser adapter returns
-`inconclusive`; only five passing evidence slots return `passed`. Maggie does
+`inconclusive`; only all configured evidence slots return `passed`. Maggie does
 not fabricate browser, rendered, or deployment evidence and does not deploy
 from this command. See
 [`readiness-v1.schema.json`](../../bundled-contracts/maggie-deployment/readiness-v1.schema.json).

package/bundled-skills/maggie-design/SKILL.md

@@ -2,7 +2,7 @@
 name: maggie-design
 description: Design authorized interior pages, review rendered responsive layouts, or explicitly rebrand a packaged homepage/template. Use rebrand only with a named source brand and target brand.
 metadata:
-  version: 1.4.0
+  version: 1.5.0
 ---
 
 # Maggie Design
@@ -55,9 +55,18 @@ Use `missing`, `unknown`, and `coverage` from the versioned
 name map is reported as evidence only; it must not be treated as proof that a
 glyph exists. Fix the source token or add the runtime definition before
 shipping. The inventory compares a scoped runtime icon family (`ph-*`, `fa-*`,
-or `lucide-*`), normalizes family prefixes, and ignores inline SVG IDs and font
-filename noise. Do not paste private source, URLs with credentials, or user
-data into the report.
+or `lucide-*`), including compound CSS selectors such as
+`.ph.ph-arrow-square-out`, normalizes family prefixes, and ignores inline SVG
+IDs and font filename noise. Do not paste private source, URLs with
+credentials, or user data into the report.
+
+Inventory is static name coverage, not proof that the browser painted a glyph.
+For every new or changed icon control, pair it with the QA `icon-rendered`
+assertion: the host browser adapter must record a visible glyph, positive
+rendered width and height, and an accessible label. If the runtime font/map
+cannot render the icon, add an approved runtime definition or inline SVG
+fallback and rerun both checks. Never release a source token solely because
+typecheck or build succeeded.
 
 ## Automatic memory hook
 

package/bundled-skills/maggie-qa-workflow/SKILL.md

@@ -2,7 +2,7 @@
 name: maggie-qa-workflow
 description: Run scenario-based browser QA with explicit evidence, fix/retest lifecycle, and release-gate decisions for web projects.
 metadata:
-  version: 1.1.0
+  version: 1.2.0
 ---
 
 # Maggie QA Workflow
@@ -91,10 +91,14 @@ HTTP status evidence, a screenshot/reference, and boolean results for runtime
 checks such as `text-present`, `text-absent`, `meta`, `link-absent`, or
 `redirect`. For dialogs and drawers, `scroll-owner-count` records the browser
 runtime's computed number of intentional scroll owners and must use
-`expected: 1`. Source/class/markup-only checks are rejected. The audit stores
-assertion IDs and safe pass/fail metadata, never response bodies, credentials,
-or cookies. A passing assertion audit complements browser evidence; it does
-not replace the host adapter's actual HTTP and screenshot capture.
+`expected: 1`. For an icon control, `icon-rendered` records browser-runtime
+evidence with `actual.visible: true`, positive `actual.width` and
+`actual.height`, and `actual.accessibleLabel: true`; a blank glyph, zero-sized
+glyph, or unlabelled control fails the audit even when build/typecheck passes.
+Source/class/markup-only checks are rejected. The audit stores assertion IDs
+and safe pass/fail metadata, never response bodies, credentials, or cookies. A
+passing assertion audit complements browser evidence; it does not replace the
+host adapter's actual HTTP and screenshot capture.
 
 ## Gate and release evidence
 

package/bundled-skills/maggie-service-booking/SKILL.md

@@ -2,7 +2,7 @@
 name: maggie-service-booking
 description: Import, synchronise, validate, and design SPA service pages from a booking provider such as Fresha. Use for service catalogues, treatment variants, prices, durations, booking links, payment links, and booking-aware page generation.
 metadata:
-  version: 1.2.0
+  version: 1.3.0
 ---
 
 # Maggie Service Booking
@@ -136,6 +136,13 @@ python3 tools/clis/maggie_service_booking.py retirement-audit \
   --project . \
   --catalogue .maggie/booking/services.json \
   --evidence .maggie/booking/retirement-evidence.json
+
+# Validate independent, pollable onboarding jobs before provider research or
+# public service generation. The manifest contains no credentials or payloads.
+maggie service orchestration-validate \
+  --project . \
+  --manifest .maggie/booking/onboarding-orchestration.json \
+  --output docs/service-onboarding-orchestration.json
 ```
 
 `import` creates the first catalogue. `sync` compares the newly imported
@@ -159,6 +166,33 @@ evidence artifact and validates the selected ending (`pending`, `redirect`,
 `tombstone`, or `gone`), HTTP status, booking suppression, unavailable/noindex
 signals, and sitemap exclusion. It never stores response bodies or decides a
 redirect destination for the host.
+
+## Asynchronous onboarding contract
+
+Provider onboarding is three independent state machines: `import` owns the
+provider catalogue, `search` owns local discovery results, and `research` owns
+website research. Each job must have a unique `jobId`, unique
+`idempotencyKey`, bounded `attempt`/`maxAttempts`, a current state and history,
+an owner, a pollable `statusRef`, and an explicit `nextAction`. State history
+is validated so retries cannot silently become successes. `fieldOwnership`
+ensures that one workflow cannot overwrite another workflow's fields; the host
+adapter remains responsible for actual persistence and queue execution.
+
+Validate the redacted orchestration snapshot before provider research and
+again before public generation:
+
+```bash
+maggie service orchestration-validate \
+  --project . \
+  --manifest .maggie/booking/onboarding-orchestration.json \
+  --output docs/service-onboarding-orchestration.json
+```
+
+The contract is documented in
+[`onboarding-orchestration-v1.schema.json`](../../bundled-contracts/maggie-service-booking/onboarding-orchestration-v1.schema.json).
+It is provider-neutral and does not accept credentials, provider response
+bodies, or arbitrary filesystem paths in the poll reference.
+
 `convert-page` imports a normal page as a draft service without inventing
 booking facts. `match-pages` reads filesystem pages plus `docs/pages.json` and
 `docs/page-content.json`, writes candidate evidence to both `.maggie/booking`

package/bundled-tools/clis/maggie_deployment_parity.py

@@ -0,0 +1,170 @@
+#!/usr/bin/env python3
+"""Validate provider-neutral worker/browser runtime parity evidence before canary traffic."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+from typing import Any
+
+
+SCHEMA = "maggie-deployment-runtime-parity.v1"
+ENVIRONMENTS = {"development", "staging", "production"}
+SAFE_ID = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$")
+
+
+def load(path: Path) -> dict[str, Any]:
+    try:
+        value = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as error:
+        raise ValueError(f"cannot read parity evidence: {error}") from error
+    if not isinstance(value, dict):
+        raise ValueError("parity evidence root must be an object")
+    return value
+
+
+def non_empty_strings(value: object, field: str, errors: list[str]) -> list[str]:
+    if not isinstance(value, list) or any(not isinstance(item, str) or not item.strip() for item in value):
+        errors.append(f"{field} must be an array of non-empty strings")
+        return []
+    return value
+
+
+def validate(payload: dict[str, Any]) -> list[str]:
+    errors: list[str] = []
+    if payload.get("schemaVersion") != SCHEMA:
+        errors.append(f"schemaVersion must be {SCHEMA}")
+    if payload.get("environment") not in ENVIRONMENTS:
+        errors.append("environment must be development, staging, or production")
+    if payload.get("passed") is not True:
+        errors.append("parity evidence is not marked passed")
+
+    worker = payload.get("worker")
+    if not isinstance(worker, dict):
+        errors.append("worker evidence must be an object")
+        worker = {}
+    config = worker.get("config")
+    if not isinstance(config, dict):
+        errors.append("worker.config evidence must be an object")
+        config = {}
+    required = non_empty_strings(config.get("required"), "worker.config.required", errors)
+    missing = non_empty_strings(config.get("missing"), "worker.config.missing", errors)
+    if not required:
+        errors.append("worker.config.required must declare at least one requirement")
+    if missing:
+        errors.append("worker.config has missing requirements")
+    if config.get("passed") is not True:
+        errors.append("worker.config did not pass")
+
+    migration = worker.get("migration")
+    privilege = migration.get("privilegeCheck") if isinstance(migration, dict) else None
+    if not isinstance(privilege, dict) or privilege.get("passed") is not True:
+        errors.append("worker.migration.privilegeCheck did not pass")
+
+    routes = worker.get("routeApis")
+    if not isinstance(routes, list) or not routes:
+        errors.append("worker.routeApis must contain at least one route check")
+        routes = []
+    for index, route in enumerate(routes):
+        prefix = f"worker.routeApis[{index}]"
+        if not isinstance(route, dict):
+            errors.append(f"{prefix} must be an object")
+            continue
+        method = route.get("method")
+        path = route.get("path")
+        status = route.get("status")
+        if not isinstance(method, str) or not re.fullmatch(r"[A-Z]{3,10}", method):
+            errors.append(f"{prefix}.method must be an uppercase HTTP method")
+        if not isinstance(path, str) or not path.startswith("/") or "?" in path or "#" in path:
+            errors.append(f"{prefix}.path must be a local route path without query or fragment")
+        if not isinstance(status, int) or isinstance(status, bool) or not 200 <= status < 400:
+            errors.append(f"{prefix}.status must be a successful HTTP status")
+        if route.get("passed") is not True:
+            errors.append(f"{prefix} did not pass")
+
+    processes = worker.get("residentProcesses")
+    if not isinstance(processes, dict):
+        errors.append("worker.residentProcesses evidence must be an object")
+        processes = {}
+    for field in ("unexpected", "stale"):
+        values = non_empty_strings(processes.get(field), f"worker.residentProcesses.{field}", errors)
+        if values:
+            errors.append(f"worker.residentProcesses contains {field} processes")
+    if processes.get("checked") is not True or processes.get("passed") is not True:
+        errors.append("worker.residentProcesses did not pass")
+
+    jobs = worker.get("sourceJobs")
+    if not isinstance(jobs, list):
+        errors.append("worker.sourceJobs must be an array")
+        jobs = []
+    for index, job in enumerate(jobs):
+        prefix = f"worker.sourceJobs[{index}]"
+        if not isinstance(job, dict):
+            errors.append(f"{prefix} must be an object")
+            continue
+        job_id = job.get("jobId")
+        if not isinstance(job_id, str) or not SAFE_ID.fullmatch(job_id):
+            errors.append(f"{prefix}.jobId must be a non-empty safe identifier")
+        if job.get("passed") is not True:
+            errors.append(f"{prefix} did not pass")
+
+    browser = payload.get("browser")
+    if not isinstance(browser, dict):
+        errors.append("browser evidence must be an object")
+        browser = {}
+    for field in ("browserVersion", "driverVersion"):
+        if not isinstance(browser.get(field), str) or not browser[field].strip():
+            errors.append(f"browser.{field} is required")
+    if browser.get("compatible") is not True:
+        errors.append("browser and driver versions are not compatible")
+    return errors
+
+
+def parity(evidence: Path, output: Path) -> int:
+    try:
+        payload = load(evidence)
+        errors = validate(payload)
+    except ValueError as error:
+        errors = [str(error)]
+    report = {
+        "schemaVersion": SCHEMA,
+        "environment": payload.get("environment") if "payload" in locals() else None,
+        "status": "passed" if not errors else "failed",
+        "passed": not errors,
+        "checks": {
+            "workerConfig": "validated",
+            "migrationPrivileges": "validated",
+            "routeApis": "validated",
+            "residentProcesses": "validated",
+            "sourceJobIds": "validated",
+            "browserDriverCompatibility": "validated",
+        },
+        "errors": errors,
+    }
+    output.parent.mkdir(parents=True, exist_ok=True)
+    output.write_text(json.dumps(report, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+    print(json.dumps({"status": report["status"], "report": str(output.resolve()), "errors": errors}, indent=2, ensure_ascii=False))
+    return 0 if not errors else 1
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--project", type=Path, default=Path.cwd())
+    parser.add_argument("--evidence", type=Path, required=True, help="sanitized host-adapter parity evidence JSON")
+    parser.add_argument("--output", type=Path, default=Path(".maggie/deployment-runtime-parity.json"))
+    args = parser.parse_args()
+    project = args.project.resolve()
+    evidence = args.evidence if args.evidence.is_absolute() else project / args.evidence
+    output = args.output if args.output.is_absolute() else project / args.output
+    try:
+        return parity(evidence, output)
+    except OSError as error:
+        print(f"BLOCKED: maggie deployment parity: {error}", file=sys.stderr)
+        return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/bundled-tools/clis/maggie_deployment_readiness.py

@@ -82,12 +82,23 @@ def validate_preflight(payload: dict[str, Any]) -> tuple[bool, str]:
     return True, "deployment preflight gates passed"
 
 
+def validate_runtime_parity(payload: dict[str, Any]) -> tuple[bool, str]:
+    if payload.get("schemaVersion") != "maggie-deployment-runtime-parity.v1":
+        return False, "runtime parity evidence schemaVersion is unsupported"
+    if payload.get("status") != "passed" or payload.get("passed") is not True:
+        return False, "worker/browser runtime parity did not pass"
+    if payload.get("errors") not in ([], None):
+        return False, "runtime parity evidence contains errors"
+    return True, "worker/browser runtime parity passed"
+
+
 VALIDATORS: dict[str, Callable[[dict[str, Any]], tuple[bool, str]]] = {
     "unitRegression": validate_unit,
     "packageSmoke": validate_package,
     "browserEvidence": validate_browser,
     "renderedCanary": validate_canary,
     "deploymentPreflight": validate_preflight,
+    "runtimeParity": validate_runtime_parity,
 }
 
 
@@ -138,6 +149,7 @@ def main() -> int:
     parser.add_argument("--browser-report", type=Path, default=Path(".maggie/verification/browser-evidence.json"))
     parser.add_argument("--rendered-canary", type=Path, default=Path(".maggie/deployment-canary.json"))
     parser.add_argument("--deployment-preflight", type=Path, default=Path(".maggie/release-preflight.json"))
+    parser.add_argument("--runtime-parity", type=Path, help="validated worker/browser parity report from maggie deployment parity")
     parser.add_argument("--output", type=Path)
     args = parser.parse_args()
     project = args.project.resolve()
@@ -147,6 +159,8 @@ def main() -> int:
         name: (getattr(args, option).resolve() if getattr(args, option).is_absolute() else project / getattr(args, option))
         for name, option in CHECKS
     }
+    if args.runtime_parity:
+        paths["runtimeParity"] = args.runtime_parity.resolve() if args.runtime_parity.is_absolute() else project / args.runtime_parity
     try:
         return readiness(project, paths, args.output)
     except (OSError, ValueError) as error:

package/bundled-tools/clis/maggie_qa_workflow.py

@@ -23,7 +23,7 @@ DEFAULT_SCENARIOS = Path(".maggie") / "scenario-manifest.json"
 VALID_STATUSES = {"pending", "pass", "fail", "blocked", "inconclusive"}
 VALID_PHASES = {"test", "fix", "retest"}
 ASSERTION_SCHEMA = "maggie.qa-assertions.v1"
-RUNTIME_ASSERTION_TYPES = {"http-status", "final-url", "text-present", "text-absent", "meta", "link-absent", "redirect", "scroll-owner-count"}
+RUNTIME_ASSERTION_TYPES = {"http-status", "final-url", "text-present", "text-absent", "meta", "link-absent", "redirect", "scroll-owner-count", "icon-rendered"}
 SOURCE_ASSERTION_TYPES = {"class-present", "class-absent", "markup-present", "markup-absent", "source-text"}
 SECRET_RE = re.compile(
     r"(?i)(bearer\s+|(?:api[_-]?key|token|secret|password|authorization|cookie)\s*[=:]\s*)[^\s,;]+"
@@ -384,6 +384,19 @@ def assertion_audit(args: argparse.Namespace) -> int:
                     item_errors.append(f"checks[{check_index}].expected must be 1 scroll owner")
                 if isinstance(check.get("actual"), int) and not isinstance(check.get("actual"), bool) and check.get("actual") != 1:
                     item_errors.append(f"checks[{check_index}] found more or fewer than one scroll owner")
+            if check_type == "icon-rendered":
+                actual = check.get("actual")
+                if not isinstance(actual, dict):
+                    item_errors.append(f"checks[{check_index}].actual must be an icon runtime measurement object")
+                else:
+                    if actual.get("visible") is not True:
+                        item_errors.append(f"checks[{check_index}] did not find a visible icon glyph")
+                    for dimension in ("width", "height"):
+                        value = actual.get(dimension)
+                        if not isinstance(value, (int, float)) or isinstance(value, bool) or value <= 0:
+                            item_errors.append(f"checks[{check_index}].actual.{dimension} must be a positive rendered dimension")
+                    if actual.get("accessibleLabel") is not True:
+                        item_errors.append(f"checks[{check_index}] icon control is missing an accessible label")
         if any(isinstance(check, dict) and check.get("passed") is False for check in checks):
             item_errors.append("one or more runtime checks failed")
         audited.append({"id": identifier, "passed": not item_errors, "errors": item_errors})

package/bundled-tools/clis/maggie_service_onboarding.py

@@ -0,0 +1,186 @@
+#!/usr/bin/env python3
+"""Validate provider-neutral asynchronous service onboarding orchestration evidence."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+from typing import Any
+
+
+SCHEMA = "maggie-service-onboarding-orchestration.v1"
+WORKFLOWS = {"import", "search", "research"}
+STATES = {"queued", "running", "succeeded", "failed", "blocked", "cancelled"}
+TRANSITIONS = {
+    "queued": {"queued", "running", "blocked", "cancelled"},
+    "running": {"running", "succeeded", "failed", "blocked", "cancelled"},
+    "failed": {"failed", "queued", "running", "blocked", "cancelled"},
+    "blocked": {"blocked", "queued", "cancelled"},
+    "succeeded": {"succeeded"},
+    "cancelled": {"cancelled"},
+}
+SAFE_ID = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$")
+SAFE_ERROR = re.compile(r"^[a-z0-9][a-z0-9._-]{0,79}$")
+
+
+def load(path: Path) -> dict[str, Any]:
+    try:
+        value = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as error:
+        raise ValueError(f"cannot read orchestration manifest: {error}") from error
+    if not isinstance(value, dict):
+        raise ValueError("orchestration manifest root must be an object")
+    return value
+
+
+def safe_status_ref(value: object) -> bool:
+    if not isinstance(value, str) or not value.strip() or "?" in value or "#" in value or "://" in value:
+        return False
+    if value.startswith("/"):
+        return True
+    return value.startswith(".") and ".." not in value
+
+
+def validate(payload: dict[str, Any]) -> list[str]:
+    errors: list[str] = []
+    if payload.get("schemaVersion") != SCHEMA:
+        errors.append(f"schemaVersion must be {SCHEMA}")
+    workflows = payload.get("workflows")
+    if not isinstance(workflows, list):
+        errors.append("workflows must be an array")
+        workflows = []
+    seen_names: set[str] = set()
+    seen_jobs: set[str] = set()
+    seen_keys: set[str] = set()
+    claimed_fields: dict[str, str] = {}
+    for index, workflow in enumerate(workflows):
+        prefix = f"workflows[{index}]"
+        if not isinstance(workflow, dict):
+            errors.append(f"{prefix} must be an object")
+            continue
+        name = workflow.get("name")
+        if name not in WORKFLOWS:
+            errors.append(f"{prefix}.name must be import, search, or research")
+        elif name in seen_names:
+            errors.append(f"{prefix}.name is duplicated")
+        else:
+            seen_names.add(name)
+        for field, seen, pattern in (("jobId", seen_jobs, SAFE_ID), ("idempotencyKey", seen_keys, SAFE_ID)):
+            value = workflow.get(field)
+            if not isinstance(value, str) or not pattern.fullmatch(value):
+                errors.append(f"{prefix}.{field} must be a non-empty safe identifier")
+            elif value in seen:
+                errors.append(f"{prefix}.{field} is duplicated")
+            else:
+                seen.add(value)
+        state = workflow.get("state")
+        if state not in STATES:
+            errors.append(f"{prefix}.state is unsupported")
+        if not isinstance(workflow.get("owner"), str) or not workflow["owner"].strip():
+            errors.append(f"{prefix}.owner is required")
+        if not safe_status_ref(workflow.get("statusRef")):
+            errors.append(f"{prefix}.statusRef must be a pollable local route or relative artifact reference")
+        attempt = workflow.get("attempt")
+        max_attempts = workflow.get("maxAttempts")
+        if not isinstance(attempt, int) or isinstance(attempt, bool) or attempt < 1:
+            errors.append(f"{prefix}.attempt must be a positive integer")
+        if not isinstance(max_attempts, int) or isinstance(max_attempts, bool) or max_attempts < 1:
+            errors.append(f"{prefix}.maxAttempts must be a positive integer")
+        if isinstance(attempt, int) and isinstance(max_attempts, int) and attempt > max_attempts:
+            errors.append(f"{prefix}.attempt cannot exceed maxAttempts")
+        next_action = workflow.get("nextAction")
+        if not isinstance(next_action, str) or not next_action.strip():
+            errors.append(f"{prefix}.nextAction is required for polling or recovery")
+
+        writes = workflow.get("writes")
+        if not isinstance(writes, list) or not writes or any(not isinstance(field, str) or not field.strip() for field in writes):
+            errors.append(f"{prefix}.writes must contain owned field paths")
+            writes = []
+        for field in writes:
+            if field in claimed_fields:
+                errors.append(f"field {field!r} is claimed by more than one workflow")
+            else:
+                claimed_fields[field] = name if isinstance(name, str) else "unknown"
+
+        history = workflow.get("history")
+        if not isinstance(history, list) or not history:
+            errors.append(f"{prefix}.history must contain the state transition history")
+            history = []
+        previous = None
+        for history_index, event in enumerate(history):
+            event_prefix = f"{prefix}.history[{history_index}]"
+            if not isinstance(event, dict) or event.get("state") not in STATES:
+                errors.append(f"{event_prefix}.state is unsupported")
+                continue
+            if not isinstance(event.get("at"), str) or not event["at"].strip():
+                errors.append(f"{event_prefix}.at is required")
+            if previous is not None and event["state"] not in TRANSITIONS[previous]:
+                errors.append(f"{event_prefix} is an invalid state transition")
+            previous = event["state"]
+        if state in STATES and history and isinstance(history[-1], dict) and history[-1].get("state") != state:
+            errors.append(f"{prefix}.history must end at the current state")
+        if state == "failed":
+            error_code = workflow.get("errorCode")
+            if not isinstance(error_code, str) or not SAFE_ERROR.fullmatch(error_code):
+                errors.append(f"{prefix}.errorCode is required for a failed workflow")
+
+    if seen_names != WORKFLOWS:
+        errors.append("workflows must contain exactly one import, search, and research state machine")
+    ownership = payload.get("fieldOwnership")
+    if not isinstance(ownership, dict):
+        errors.append("fieldOwnership must map each written field to one workflow")
+        ownership = {}
+    for field, owner in ownership.items():
+        if not isinstance(field, str) or not field.strip() or owner not in WORKFLOWS:
+            errors.append("fieldOwnership contains an invalid field owner")
+    for field, owner in claimed_fields.items():
+        if ownership.get(field) != owner:
+            errors.append(f"fieldOwnership does not assign {field!r} to its writing workflow")
+    return errors
+
+
+def orchestration(manifest: Path, output: Path) -> int:
+    try:
+        payload = load(manifest)
+        errors = validate(payload)
+    except ValueError as error:
+        errors = [str(error)]
+        payload = {}
+    workflows = payload.get("workflows") if isinstance(payload.get("workflows"), list) else []
+    report = {
+        "schemaVersion": SCHEMA,
+        "status": "passed" if not errors else "failed",
+        "passed": not errors,
+        "workflowCount": len(workflows),
+        "stateMachines": sorted(
+            {item.get("name") for item in workflows if isinstance(item, dict) and isinstance(item.get("name"), str)}
+        ),
+        "errors": errors,
+    }
+    output.parent.mkdir(parents=True, exist_ok=True)
+    output.write_text(json.dumps(report, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+    print(json.dumps({"status": report["status"], "report": str(output.resolve()), "errors": errors}, indent=2, ensure_ascii=False))
+    return 0 if not errors else 1
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--project", type=Path, default=Path.cwd())
+    parser.add_argument("--manifest", type=Path, required=True, help="sanitized orchestration contract JSON")
+    parser.add_argument("--output", type=Path, default=Path("docs/service-onboarding-orchestration.json"))
+    args = parser.parse_args()
+    project = args.project.resolve()
+    manifest = args.manifest if args.manifest.is_absolute() else project / args.manifest
+    output = args.output if args.output.is_absolute() else project / args.output
+    try:
+        return orchestration(manifest, output)
+    except OSError as error:
+        print(f"BLOCKED: maggie service orchestration-validate: {error}", file=sys.stderr)
+        return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@topy-ai/maggie",
-  "version": "0.7.23",
+  "version": "0.7.24",
   "description": "Install and manage Maggie Skills for AI coding agents",
   "license": "MIT",
   "type": "module",