@topy-ai/maggie 0.7.23 → 0.7.25

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_design.py

@@ -157,6 +157,114 @@ def validate_content_ui(project: Path, plan_path: Path, rendered_dir: Path | Non
     output = plan_path.parent / "validation.json"; output.write_text(json.dumps(result, indent=2, ensure_ascii=False) + "\n", encoding="utf-8"); print(json.dumps(result, indent=2, ensure_ascii=False)); return 0 if not errors else 1
 
 
+def app_surface_init(project: Path, route: str, auth_mode: str, force: bool, confirm: bool) -> int:
+    """Create a host-owned mobile app surface contract and QA manifest."""
+    project = project.resolve()
+    if not route.startswith("/") or "?" in route or "#" in route:
+        raise ValueError("route must be a path beginning with / and must not contain a query or hash")
+    if auth_mode not in {"email-password", "existing-session", "none"}:
+        raise ValueError("auth mode must be email-password, existing-session, or none")
+    contract = require_design_contract(project)
+    relative = route.strip("/")
+    candidates = [
+        project / relative,
+        project / "src" / "pages" / relative,
+        project / "src" / "pages" / f"{relative}.astro",
+        project / "src" / "pages" / f"{relative}.html",
+        project / "src" / "app" / relative,
+        project / "src" / "app" / relative / "page.tsx",
+    ]
+    source = next((path for path in candidates if path.is_file()), None)
+    digest = hashlib.sha256((str(project) + "\n" + route + "\n" + auth_mode).encode()).hexdigest()[:12]
+    output_dir = project / ".maggie" / "design" / "app-view" / f"app-{digest}"
+    if output_dir.exists() and not force:
+        print((output_dir / "plan.json").read_text(encoding="utf-8"), end="")
+        return 0
+    output_dir.mkdir(parents=True, exist_ok=True)
+    viewports = {"desktop": REVIEW_VIEWPORTS["desktop"], "tablet": REVIEW_VIEWPORTS["tablet"], "mobile": REVIEW_VIEWPORTS["mobile"]}
+    plan = {
+        "schemaVersion": "maggie-mobile-app-surface.v1",
+        "id": f"app-{digest}",
+        "workflow": "maggie-design",
+        "mode": "app-view-init",
+        "phase": "ready",
+        "route": route,
+        "routeSource": str(source) if source else None,
+        "designContract": contract,
+        "auth": {"mode": auth_mode, "required": auth_mode != "none", "credentialPolicy": "use-host-auth-without-recording-credentials"},
+        "shell": {"fixedHeader": True, "fixedFooter": True, "oneScrollOwner": True, "cameraMayUseFullScreenViewport": True, "hostShellSourceOfTruth": "existing homepage shell"},
+        "camera": {"requiredStates": ["permission", "ready", "gallery", "scan", "unavailable"], "controls": ["close", "gallery", "shutter", "mode"], "fallback": "show an actionable unavailable state; never leave a black screen"},
+        "decisionCriticalUi": ["card normalization", "graded-price fallback", "grade-9-to-10 economics", "scan-to-inventory or valuation transition"],
+        "viewports": viewports,
+        "requiredSteps": ["inspect-host-shell", "define-auth-gate", "define-camera-states", "capture-desktop-tablet-mobile", "signed-in-browser-qa", "accessibility-check", "route-validation", "explicit-approval"],
+        "provenance": {"hostOwnsAuthAndCamera": True, "designContractReused": True, "privateDataCopied": False},
+        "publicWrite": False,
+        "createdAt": datetime.now(timezone.utc).isoformat(),
+    }
+    evidence = {
+        "schemaVersion": "maggie-mobile-app-evidence.v1",
+        "route": route,
+        "auth": plan["auth"],
+        "shell": plan["shell"],
+        "camera": plan["camera"],
+        "viewports": {name: {"screenshot": f"{name}.png", "captured": False} for name in viewports},
+        "status": "pending",
+    }
+    qa = {"schemaVersion": "maggie-mobile-app-qa.v1", "route": route, "auth": plan["auth"], "scenarios": [
+        {"id": "shell-scroll", "viewport": "mobile", "assertions": ["fixed header and footer remain usable", "exactly one scroll owner"]},
+        {"id": "camera-permission", "viewport": "mobile", "assertions": ["permission state is explained", "denied permission shows fallback"]},
+        {"id": "camera-scan", "viewport": "mobile", "assertions": ["gallery/shutter/mode/close controls are reachable", "scan result can enter inventory or valuation"]},
+        {"id": "valuation-auth", "viewport": "desktop", "assertions": ["signed-in route does not redirect unexpectedly", "grade economics and fallback price remain legible"]},
+    ]}
+    (output_dir / "plan.json").write_text(json.dumps(plan, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+    (output_dir / "qa-scenarios.json").write_text(json.dumps(qa, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+    (output_dir / "validation.json").write_text(json.dumps(evidence, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+    (output_dir / "screenshots").mkdir(exist_ok=True)
+    print(json.dumps({"plan": str(output_dir / "plan.json"), "qaScenarios": str(output_dir / "qa-scenarios.json"), "surface": "app", "phase": "ready", "publicWrite": False}, indent=2, ensure_ascii=False))
+    return 0
+
+
+def validate_app_surface(project: Path, plan_path: Path, rendered_dir: Path | None, runtime_evidence: Path | None, confirm: bool) -> int:
+    """Validate signed-in app evidence and responsive screenshots."""
+    project = project.resolve(); plan_path = plan_path.resolve()
+    if not plan_path.exists(): raise ValueError(f"app surface plan not found: {plan_path}")
+    plan = json.loads(plan_path.read_text(encoding="utf-8")); errors = []
+    if plan.get("workflow") != "maggie-design" or plan.get("mode") != "app-view-init": errors.append("invalid mobile app surface plan")
+    if plan.get("publicWrite") is not False: errors.append("publicWrite must remain false before approval")
+    if not plan.get("shell", {}).get("oneScrollOwner"): errors.append("app surface must define one scroll owner")
+    if not plan.get("auth", {}).get("credentialPolicy"): errors.append("app surface must define a credential policy")
+    try: require_design_contract(project)
+    except ValueError as error: errors.append(str(error))
+    evidence = {}
+    evidence_path = runtime_evidence.resolve() if runtime_evidence else plan_path.parent / "runtime-evidence.json"
+    if evidence_path.is_file():
+        try: evidence = json.loads(evidence_path.read_text(encoding="utf-8"))
+        except json.JSONDecodeError: errors.append("runtime evidence is not valid JSON")
+    else:
+        errors.append("runtime evidence file is required")
+    if evidence:
+        if evidence.get("schemaVersion") != "maggie-mobile-app-evidence.v1": errors.append("runtime evidence schemaVersion is invalid")
+        if evidence.get("route") != plan.get("route"): errors.append("runtime evidence route does not match plan")
+        auth = evidence.get("auth", {})
+        if plan.get("auth", {}).get("required") and auth.get("signedIn") is not True: errors.append("signed-in evidence is required for this app route")
+        shell = evidence.get("shell", {})
+        if shell.get("fixedHeader") is not True or shell.get("fixedFooter") is not True or shell.get("scrollOwnerCount") != 1: errors.append("runtime evidence must prove fixed shell and one scroll owner")
+        camera = evidence.get("camera", {})
+        camera_states = set(camera.get("states", [])) if isinstance(camera, dict) else set()
+        if not set(plan.get("camera", {}).get("requiredStates", [])).issubset(camera_states): errors.append("runtime evidence is missing a required camera state")
+    screenshot_status = {}
+    for name in ("desktop", "tablet", "mobile"):
+        path = (rendered_dir / f"{name}.png") if rendered_dir else plan_path.parent / "screenshots" / f"{name}.png"
+        valid = path.is_file() and path.read_bytes()[:8] == b"\x89PNG\r\n\x1a\n"
+        screenshot_status[name] = {"path": str(path), "validPng": valid}
+        if not valid: errors.append(f"missing valid {name} screenshot")
+    result = {"schemaVersion": "maggie-mobile-app-validation.v1", "plan": str(plan_path), "route": plan.get("route"), "screenshots": screenshot_status, "runtimeEvidence": str(evidence_path), "checks": {"fixedShell": not any("fixed shell" in error for error in errors), "signedInRoute": not any("signed-in" in error for error in errors), "cameraStates": not any("camera state" in error for error in errors), "publicWriteBlocked": plan.get("publicWrite") is False}, "status": "passed" if not errors else "failed", "errors": errors, "validatedAt": datetime.now(timezone.utc).isoformat()}
+    if confirm:
+        plan_path.parent.joinpath("validation.json").write_text(json.dumps(result, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+    print(json.dumps(result, indent=2, ensure_ascii=False))
+    return 0 if not errors else 1
+
+
 def rebrand_template(args: argparse.Namespace) -> int:
     """Apply an explicit brand identity to a packaged homepage template."""
     template = args.template.resolve()
@@ -547,6 +655,7 @@ def in_place_job(project: Path, routes: list[str], force: bool = False, content_
             project / relative,
             project / "src" / "pages" / relative,
             project / "src" / "app" / relative,
+            project / "src" / "pages" / f"{relative}.astro",
             project / "src" / "pages" / f"{relative}.html",
             project / "src" / "app" / relative / "page.tsx",
         ]
@@ -680,7 +789,7 @@ commands:
   status       show a design job and its per-step progress
   resume       restart a failed design workflow
   author       plan an original first-party page
-  reference-ui, init, validate-ui, rebrand, review
+  reference-ui, init, validate-ui, app-init, app-validate, rebrand, review
 """)
         return 0
     if len(sys.argv) > 1 and sys.argv[1] == "reference-ui":
@@ -719,6 +828,30 @@ commands:
             return validate_content_ui(args.project, args.plan, args.rendered_dir, args.confirm)
         except (OSError, ValueError, json.JSONDecodeError) as error:
             print(f"BLOCKED: maggie-design validate-ui: {error}", file=sys.stderr); return 1
+    if len(sys.argv) > 1 and sys.argv[1] == "app-init":
+        command = argparse.ArgumentParser(description="Create a mobile app surface contract with signed-in QA scenarios.")
+        command.add_argument("--project", type=Path, default=Path.cwd())
+        command.add_argument("--route", required=True)
+        command.add_argument("--auth-mode", choices=["email-password", "existing-session", "none"], default="email-password")
+        command.add_argument("--force", action="store_true")
+        command.add_argument("--confirm", action="store_true")
+        args = command.parse_args(sys.argv[2:])
+        try:
+            return app_surface_init(args.project, args.route, args.auth_mode, args.force, args.confirm)
+        except (OSError, ValueError, json.JSONDecodeError) as error:
+            print(f"BLOCKED: maggie-design app-init: {error}", file=sys.stderr); return 1
+    if len(sys.argv) > 1 and sys.argv[1] == "app-validate":
+        command = argparse.ArgumentParser(description="Validate mobile app runtime evidence and responsive screenshots.")
+        command.add_argument("--project", type=Path, default=Path.cwd())
+        command.add_argument("--plan", type=Path, required=True)
+        command.add_argument("--rendered-dir", type=Path)
+        command.add_argument("--runtime-evidence", type=Path)
+        command.add_argument("--confirm", action="store_true")
+        args = command.parse_args(sys.argv[2:])
+        try:
+            return validate_app_surface(args.project, args.plan, args.rendered_dir, args.runtime_evidence, args.confirm)
+        except (OSError, ValueError, json.JSONDecodeError) as error:
+            print(f"BLOCKED: maggie-design app-validate: {error}", file=sys.stderr); return 1
     if len(sys.argv) > 1 and sys.argv[1] == "rebrand":
         rebrand = argparse.ArgumentParser(description="Apply an explicit brand identity to a packaged marketplace template.")
         rebrand.add_argument("--template", type=Path, required=True)

package/bundled-tools/clis/maggie_feedback.py

@@ -27,6 +27,7 @@ LOCAL_PATH_RE = re.compile(
     r"\\\\[^\\/\s,;:)\]}]+(?:[\\/]+[^\\/\s,;:)\]}]+)+)"
 )
 VERSION_RE = re.compile(r"\d+\.\d+\.\d+(?:[-+][A-Za-z0-9.-]+)?")
+SAFE_BATCH_ID_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._:-]{0,159}$")
 ACKNOWLEDGEMENT_KEYS = ("status", "feedbackId", "requestId")
 REPO_ROOT = Path(__file__).resolve().parents[2]
 
@@ -45,10 +46,25 @@ def project_fingerprint(project: Path) -> str:
 
 
 def installed_version(project: Path) -> str:
-    """Resolve the exact runtime version and fail closed on source drift."""
+    """Resolve the exact runtime version, preferring the running package."""
     if os.environ.get("MAGGIE_VERSION"):
         value = safe_text(os.environ["MAGGIE_VERSION"])
         return value if VERSION_RE.fullmatch(value) else "unknown"
+
+    # A consumer project can retain an old .maggie/install.json after npm
+    # upgrade. The package actually being executed is stronger evidence.
+    package_versions = []
+    for parent in (project.resolve(), *project.resolve().parents):
+        package_path = parent / "node_modules" / "@topy-ai" / "maggie" / "package.json"
+        try:
+            value = json.loads(package_path.read_text(encoding="utf-8")).get("version", "")
+            if VERSION_RE.fullmatch(str(value)):
+                package_versions.append(str(value))
+        except (OSError, ValueError, json.JSONDecodeError, AttributeError):
+            continue
+    if package_versions:
+        return package_versions[0] if len(set(package_versions)) == 1 else "unknown"
+
     install_path = project / ".maggie" / "install.json"
     try:
         value = json.loads(install_path.read_text(encoding="utf-8")).get("version", "")
@@ -102,6 +118,20 @@ def collect(args: argparse.Namespace) -> int:
     validation = safe_text(args.validation or report.get("validation"))
     if fixed and (not resolution or not validation):
         raise ValueError("fixed feedback requires non-empty --resolution and --validation")
+    batch_id = safe_text(getattr(args, "batch_id", ""))
+    batch_index = getattr(args, "batch_index", None)
+    batch_size = getattr(args, "batch_size", None)
+    if batch_id:
+        if not SAFE_BATCH_ID_RE.fullmatch(batch_id):
+            raise ValueError("batch ID is invalid")
+        if not isinstance(batch_index, int) or isinstance(batch_index, bool) or batch_index < 0:
+            raise ValueError("batch index is required when batch ID is provided")
+        if not isinstance(batch_size, int) or isinstance(batch_size, bool) or batch_size < 1 or batch_index >= batch_size:
+            raise ValueError("batch size must be positive and greater than batch index")
+    priority = safe_text(getattr(args, "priority", "") or "normal").lower()
+    if priority not in {"low", "normal", "high", "critical"}:
+        raise ValueError("priority must be low, normal, high, or critical")
+    affected_cli = safe_text(getattr(args, "affected_cli", ""))
     context = {"projectFingerprint": project_fingerprint(project)}
     if args.allow_project_context and args.context_note:
         context["note"] = safe_text(args.context_note)
@@ -124,12 +154,16 @@ def collect(args: argparse.Namespace) -> int:
         "fixed": fixed,
         "resolution": resolution,
         "validation": validation,
+        "priority": priority,
+        "affectedCli": affected_cli,
         "attachments": [attachment(value) for value in args.screenshot],
         "environment": {"os": platform.system().lower(), "python": platform.python_version()},
         "privacy": {"secretsRedacted": True, "projectContextAllowed": bool(args.allow_project_context)},
         "projectContext": context if args.allow_project_context else None,
         "submission": {"status": "draft"},
     }
+    if batch_id:
+        data["batch"] = {"batchId": batch_id, "index": batch_index, "size": batch_size}
     directory = project / ".maggie" / "feedback"
     directory.mkdir(parents=True, exist_ok=True)
     path = directory / f"{data['feedbackId']}.json"
@@ -144,7 +178,11 @@ def collect(args: argparse.Namespace) -> int:
 
 
 def to_markdown(data: dict) -> str:
-    lines = [f"# Maggie feedback: {data.get('summary') or data.get('type')}", "", "<!-- Generated by maggie feedback. Secrets and local paths are omitted. -->", "", "## Run", "", f"- Skill: `{data.get('skill')}`", f"- Maggie version: `{data.get('maggieVersion')}`", f"- Run ID: `{data.get('runId') or 'not provided'}`", f"- Phase: `{data.get('phase') or 'not provided'}`", f"- Status: `{data.get('status')}`", f"- Error fingerprint: `{data.get('errorFingerprint') or 'not provided'}`", "", "## Report", "", f"**Summary:** {data.get('summary') or 'Not provided'}", "", f"**Expected:** {data.get('expected') or 'Not provided'}", "", f"**Actual:** {data.get('actual') or 'Not provided'}", ""]
+    batch = data.get("batch") or {}
+    lines = [f"# Maggie feedback: {data.get('summary') or data.get('type')}", "", "<!-- Generated by maggie feedback. Secrets and local paths are omitted. -->", "", "## Run", "", f"- Skill: `{data.get('skill')}`", f"- Maggie version: `{data.get('maggieVersion')}`", f"- Run ID: `{data.get('runId') or 'not provided'}`", f"- Phase: `{data.get('phase') or 'not provided'}`", f"- Status: `{data.get('status')}`", f"- Priority: `{data.get('priority') or 'normal'}`", f"- Affected CLI: `{data.get('affectedCli') or 'not provided'}`", f"- Error fingerprint: `{data.get('errorFingerprint') or 'not provided'}`"]
+    if batch:
+        lines.append(f"- Batch: `{batch.get('batchId')}` ({batch.get('index', 0) + 1}/{batch.get('size')})")
+    lines += ["", "## Report", "", f"**Summary:** {data.get('summary') or 'Not provided'}", "", f"**Expected:** {data.get('expected') or 'Not provided'}", "", f"**Actual:** {data.get('actual') or 'Not provided'}", ""]
     if data.get("stepsToReproduce"):
         lines += ["**Steps to reproduce:**", ""] + [f"{index}. {step}" for index, step in enumerate(data["stepsToReproduce"], 1)] + [""]
     lines += [f"**Fixed:** {'yes' if data.get('fixed') else 'no'}", f"**Resolution:** {data.get('resolution') or 'Not provided'}", f"**Validation:** {data.get('validation') or 'Not provided'}", "", "## Privacy", "", f"- Project context allowed: `{bool(data.get('privacy', {}).get('projectContextAllowed'))}`", f"- Attachments: `{len(data.get('attachments', []))}` metadata-only reference(s)", ""]
@@ -211,6 +249,57 @@ def list_feedback(args: argparse.Namespace) -> int:
     return 0
 
 
+def collect_batch(args: argparse.Namespace) -> int:
+    """Create one privacy-safe draft per item while retaining shared batch context."""
+    manifest = load_json(Path(args.batch_file).expanduser().resolve())
+    batch_id = safe_text(manifest.get("batchId"))
+    if not SAFE_BATCH_ID_RE.fullmatch(batch_id):
+        raise ValueError("batch file requires a safe batchId")
+    items = manifest.get("items")
+    if not isinstance(items, list) or not items or len(items) > 50:
+        raise ValueError("batch file requires between 1 and 50 items")
+    shared = {
+        "skill": safe_text(manifest.get("skill")),
+        "run_id": safe_text(manifest.get("runId")),
+        "phase": safe_text(manifest.get("phase")),
+        "priority": safe_text(manifest.get("priority") or "normal"),
+        "affected_cli": safe_text(manifest.get("affectedCli")),
+    }
+    paths = []
+    for index, item in enumerate(items):
+        if not isinstance(item, dict):
+            raise ValueError(f"items[{index}] must be an object")
+        values = {
+            "project": args.project,
+            "run_report": None,
+            "skill": safe_text(item.get("skill") or shared["skill"]),
+            "run_id": safe_text(item.get("runId") or shared["run_id"]),
+            "type": item.get("type", "bug"),
+            "phase": safe_text(item.get("phase") or shared["phase"]),
+            "summary": item.get("summary", ""),
+            "expected": item.get("expected", ""),
+            "actual": item.get("actual", ""),
+            "error_fingerprint": item.get("errorFingerprint", ""),
+            "reproduce": item.get("stepsToReproduce", []),
+            "fixed": item.get("fixed") is True,
+            "resolution": item.get("resolution", ""),
+            "validation": item.get("validation", ""),
+            "screenshot": item.get("screenshots", []),
+            "allow_project_context": False,
+            "context_note": "",
+            "batch_id": batch_id,
+            "batch_index": index,
+            "batch_size": len(items),
+            "priority": item.get("priority") or shared["priority"],
+            "affected_cli": item.get("affectedCli") or shared["affected_cli"],
+        }
+        if not isinstance(values["reproduce"], list): values["reproduce"] = []
+        if not isinstance(values["screenshot"], list): values["screenshot"] = []
+        paths.append(collect(argparse.Namespace(**values)))
+    print(json.dumps({"batchId": batch_id, "count": len(paths), "status": "drafts-created"}, ensure_ascii=False))
+    return 0
+
+
 def main() -> int:
     parser = argparse.ArgumentParser(description=__doc__)
     parser.add_argument("--project", default=".")
@@ -235,6 +324,14 @@ def main() -> int:
     collect_parser.add_argument("--screenshot", action="append", default=[])
     collect_parser.add_argument("--allow-project-context", action="store_true")
     collect_parser.add_argument("--context-note", default="")
+    collect_parser.add_argument("--batch-id", default="")
+    collect_parser.add_argument("--batch-index", type=int)
+    collect_parser.add_argument("--batch-size", type=int)
+    collect_parser.add_argument("--priority", choices=("low", "normal", "high", "critical"), default="normal")
+    collect_parser.add_argument("--affected-cli", default="")
+    batch_parser = sub.add_parser("batch")
+    batch_parser.add_argument("--project", default=argparse.SUPPRESS)
+    batch_parser.add_argument("--batch-file", required=True)
     preview_parser = sub.add_parser("preview")
     preview_parser.add_argument("feedback")
     preview_parser.add_argument("--format", choices=("json", "markdown"), default="json")
@@ -246,6 +343,7 @@ def main() -> int:
     args = parser.parse_args()
     try:
         if args.command == "collect": return collect(args)
+        if args.command == "batch": return collect_batch(args)
         if args.command == "preview": return preview(args)
         if args.command == "submit": return submit(args)
         return list_feedback(args)

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})