@topy-ai/maggie 0.7.44 → 0.7.46

package/bundled-tools/clis/maggie_release.py

@@ -20,6 +20,21 @@ from urllib.parse import urljoin, urlsplit
 
 
 ROOT = Path(__file__).resolve().parent
+PROFILE_SCHEMA = "maggie-release-profile.v1"
+PROFILE_CAPABILITIES = {
+    "deployment",
+    "scenario-qa",
+    "social-card-audit",
+    "migration",
+    "maggiedash-health",
+    "schedule",
+    "analytics-contract",
+    "analytics-release-gate",
+    "service-facts",
+    "maggiedash-schema",
+    "editorial-review",
+    "durable-site-evidence",
+}
 
 
 def safe_tail(value: str, limit: int = 1200) -> str:
@@ -52,6 +67,68 @@ def run_gate(name: str, command: list[str], cwd: Path) -> dict:
     }
 
 
+def load_release_profile(project: Path, requested: str | None) -> tuple[dict, dict]:
+    """Load an explicit project capability manifest without guessing scope."""
+    path = Path(requested).resolve() if requested else project / ".maggie" / "release-profile.json"
+    errors: list[str] = []
+    profile: dict = {}
+    try:
+        profile = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as exc:
+        errors.append(f"release profile {path}: {exc}")
+    if not isinstance(profile, dict):
+        errors.append("release profile must be a JSON object")
+        profile = {}
+    if profile.get("schemaVersion") != PROFILE_SCHEMA:
+        errors.append(f"schemaVersion must be {PROFILE_SCHEMA}")
+    name = profile.get("profile")
+    if not isinstance(name, str) or not re.fullmatch(r"[a-z][a-z0-9-]{1,63}", name):
+        errors.append("profile must be a safe non-empty identifier")
+    capabilities = profile.get("capabilities")
+    if not isinstance(capabilities, list) or not capabilities:
+        errors.append("capabilities must be a non-empty array")
+        capabilities = []
+    elif len(set(capabilities)) != len(capabilities):
+        errors.append("capabilities must not contain duplicates")
+    unknown = sorted(set(capabilities) - PROFILE_CAPABILITIES) if isinstance(capabilities, list) else []
+    if unknown:
+        errors.append("unsupported capabilities: " + ", ".join(unknown))
+    if "deployment" not in capabilities:
+        errors.append("capabilities must include deployment for a release")
+    valid = not errors
+    return (
+        {
+            "path": str(path),
+            "profile": name if isinstance(name, str) else None,
+            "projectType": profile.get("projectType"),
+            "capabilities": capabilities if isinstance(capabilities, list) else [],
+            "valid": valid,
+            "errors": errors,
+        },
+        profile if valid else {},
+    )
+
+
+def profile_gate(profile: dict) -> dict:
+    """Return the explicit profile validation as a normal release gate."""
+    return {
+        "name": "release-profile",
+        "passed": profile["valid"],
+        "exitCode": 0 if profile["valid"] else 1,
+        "result": {
+            "passed": profile["valid"],
+            "schemaVersion": PROFILE_SCHEMA if profile["valid"] else None,
+            "profile": profile.get("profile"),
+            "projectType": profile.get("projectType"),
+            "capabilities": profile.get("capabilities", []),
+            "path": profile.get("path"),
+            "errors": profile.get("errors", []),
+            "mutation": "not executed",
+        },
+        "stderr": "",
+    }
+
+
 def build_gate(project: Path) -> dict:
     """Run the project's declared typecheck and build commands."""
     package_path = project / "package.json"
@@ -84,19 +161,23 @@ def build_gate(project: Path) -> dict:
     }
 
 
-def build_gates(project: Path, environment: str, target: str, include_compatibility: bool) -> list[tuple[str, list[str]]]:
+def build_gates(project: Path, environment: str, target: str, capabilities: set[str]) -> list[tuple[str, list[str]]]:
     python = sys.executable
-    gates: list[tuple[str, list[str]]] = [
-        ("deployment-preflight", [python, str(ROOT / "maggie_deployment.py"), str(project), "--target", target, "--environment", environment]),
-        ("migration-preflight", [python, str(ROOT / "maggie_migration.py"), "--project", str(project), "--environment", environment]),
-        ("maggiedash-health", [python, str(ROOT / "maggie_health.py"), "--project", str(project), "--environment", environment]),
-        ("schedule-manifest", [python, str(ROOT / "maggie_schedule.py"), str(project / ".maggie" / "schedule.json"), "--project", str(project)]),
-        ("analytics-contract", [python, str(ROOT / "maggie_analytics.py"), "--project", str(project), "--environment", environment]),
-        ("service-facts", [python, str(ROOT / "maggie_service_booking.py"), "fact-audit", "--project", str(project)]),
-    ]
-    if include_compatibility:
-        gates.append(("maggiedash-schema", [python, str(ROOT / "maggie_migration.py"), "--project", str(project), "--environment", environment]))
-    return gates
+    deployment_command = [python, str(ROOT / "maggie_deployment.py"), str(project), "--target", target, "--environment", environment]
+    if target in {"vps", "vps-with-cloudflare-dns", "detected"}:
+        deployment_command.append("--require-deployer")
+    commands = {
+        "deployment": ("deployment-preflight", deployment_command),
+        "migration": ("migration-preflight", [python, str(ROOT / "maggie_migration.py"), "--project", str(project), "--environment", environment]),
+        "maggiedash-health": ("maggiedash-health", [python, str(ROOT / "maggie_health.py"), "--project", str(project), "--environment", environment]),
+        "schedule": ("schedule-manifest", [python, str(ROOT / "maggie_schedule.py"), str(project / ".maggie" / "schedule.json"), "--project", str(project)]),
+        "analytics-contract": ("analytics-contract", [python, str(ROOT / "maggie_analytics.py"), "--project", str(project), "--environment", environment]),
+        "service-facts": ("service-facts", [python, str(ROOT / "maggie_service_booking.py"), "fact-audit", "--project", str(project)]),
+        "maggiedash-schema": ("maggiedash-schema", [python, str(ROOT / "maggie_migration.py"), "--project", str(project), "--environment", environment]),
+    }
+    return [commands[capability] for capability in (
+        "deployment", "migration", "maggiedash-health", "schedule", "analytics-contract", "service-facts", "maggiedash-schema"
+    ) if capability in capabilities]
 
 
 def evidence_gate(project: Path, environment: str) -> dict:
@@ -371,6 +452,7 @@ def main() -> int:
     parser.add_argument("project", nargs="?", default=".")
     parser.add_argument("--environment", choices=("staging", "production"), default="staging")
     parser.add_argument("--target", choices=("vps", "vps-with-cloudflare-dns", "cloudflare", "detected"), default="vps-with-cloudflare-dns")
+    parser.add_argument("--profile", help="explicit release capability manifest; defaults to .maggie/release-profile.json")
     parser.add_argument("--output", help="release evidence JSON path")
     parser.add_argument("--skip-compatibility", action="store_true", help="skip the optional schema rehearsal; not recommended for release")
     parser.add_argument("--base-url", help="optional live/staging URL for homepage, admin redirect and 404 smoke")
@@ -385,14 +467,24 @@ def main() -> int:
     if not project.is_dir():
         parser.error(f"project directory does not exist: {project}")
 
-    gates = []
+    profile, _profile_payload = load_release_profile(project, args.profile)
+    capabilities = set(profile.get("capabilities", [])) if profile["valid"] else set()
+    if args.skip_compatibility:
+        capabilities.discard("maggiedash-schema")
+    gates = [profile_gate(profile)]
     gates.append(changed_surface_gate(project))
-    gates.append(qa_gate(project, args.environment, args.base_url))
+    if "scenario-qa" in capabilities:
+        gates.append(qa_gate(project, args.environment, args.base_url))
+    else:
+        gates.append({"name": "scenario-qa", "passed": True, "exitCode": 0, "result": {"passed": True, "state": "skipped", "reason": "scenario-qa is not declared by the release profile"}, "stderr": ""})
     gates.append(build_gate(project))
-    gates.append(social_card_gate(project))
-    for name, command in build_gates(project, args.environment, args.target, not args.skip_compatibility):
+    if "social-card-audit" in capabilities:
+        gates.append(social_card_gate(project))
+    else:
+        gates.append({"name": "social-card-audit", "passed": True, "exitCode": 0, "result": {"passed": True, "state": "skipped", "reason": "social-card-audit is not declared by the release profile"}, "stderr": ""})
+    for name, command in build_gates(project, args.environment, args.target, capabilities):
         gates.append(run_gate(name, command, project))
-    if args.analytics_release_gate:
+    if args.analytics_release_gate or "analytics-release-gate" in capabilities:
         evidence = {
             "--contract": args.analytics_contract,
             "--render-report": args.analytics_render_report,
@@ -407,8 +499,14 @@ def main() -> int:
         for name, value in evidence.items():
             analytics_command.extend([name, value])
         gates.append(run_gate("analytics-release-gate", analytics_command, project))
-    gates.append(editorial_gate(project))
-    gates.append(evidence_gate(project, args.environment))
+    if "editorial-review" in capabilities:
+        gates.append(editorial_gate(project))
+    else:
+        gates.append({"name": "editorial-review", "passed": True, "exitCode": 0, "result": {"passed": True, "state": "skipped", "reason": "editorial-review is not declared by the release profile"}, "stderr": ""})
+    if "durable-site-evidence" in capabilities:
+        gates.append(evidence_gate(project, args.environment))
+    else:
+        gates.append({"name": "durable-site-evidence", "passed": True, "exitCode": 0, "result": {"passed": True, "state": "skipped", "reason": "durable-site-evidence is not declared by the release profile"}, "stderr": ""})
     if args.base_url:
         gates.append(runtime_smoke(args.base_url))
 
@@ -418,6 +516,13 @@ def main() -> int:
         "project": str(project),
         "environment": args.environment,
         "target": args.target,
+        "profile": {
+            "path": profile["path"],
+            "name": profile.get("profile"),
+            "projectType": profile.get("projectType"),
+            "capabilities": profile.get("capabilities", []),
+            "valid": profile["valid"],
+        },
         "mutation": "not executed",
         "passed": all(gate["passed"] for gate in gates),
         "gates": gates,

package/bundled-tools/runtime/browser_capability.py

@@ -0,0 +1,143 @@
+"""Detect whether a configured browser adapter can run Maggie audits."""
+
+from __future__ import annotations
+
+import hashlib
+import os
+import shutil
+import subprocess
+from pathlib import Path
+
+
+SCHEMA_VERSION = "maggie-browser-capability.v1"
+REQUIRED_COMMANDS = ("goto", "viewport", "screenshot", "js", "eval")
+INTERACTION_COMMANDS = ("click", "fill", "type", "press", "wait", "is")
+HELP_TIMEOUT_SECONDS = 5
+
+
+def _safe_name(value: object) -> str:
+    text = Path(str(value or "")).name
+    return text if text and text not in {".", ".."} else "unknown"
+
+
+def _path_fingerprint(value: str) -> str:
+    return "sha256:" + hashlib.sha256(value.encode("utf-8")).hexdigest()
+
+
+def _guidance(status: str) -> list[str]:
+    if status == "missing":
+        return [
+            "Install or enable an authorized Chrome/Playwright/gstack browser adapter.",
+            "Pass its executable path explicitly with --browse <adapter-path>.",
+            "If using Playwright locally, install the browser runtime with: npx playwright install chromium.",
+        ]
+    return [
+        "Pass the executable for the intended browser adapter, not a desktop URL/file opener.",
+        "The adapter must expose --help and support goto, viewport, screenshot, js, and eval.",
+        "If using gstack, pass the absolute path to gstack browse/dist/browse.",
+    ]
+
+
+def discover_browser_adapter(requested: str | Path) -> dict:
+    """Return a redacted, actionable capability report without opening a page."""
+    requested_text = str(requested or "").strip()
+    requested_name = _safe_name(requested_text)
+    report = {
+        "schemaVersion": SCHEMA_VERSION,
+        "adapter": {
+            "requested": requested_name,
+            "requestedPathFingerprint": _path_fingerprint(requested_text) if requested_text else None,
+        },
+        "status": "missing",
+        "checks": {
+            "resolved": False,
+            "regularFile": False,
+            "executable": False,
+            "help": False,
+            "requiredCommands": False,
+            "interactionCommands": False,
+        },
+        "requiredCommands": list(REQUIRED_COMMANDS),
+        "fallback": _guidance("missing"),
+    }
+    if not requested_text:
+        report["errorCode"] = "adapter-not-found"
+        report["message"] = "No browser adapter was provided."
+        return report
+
+    resolved = shutil.which(requested_text)
+    if resolved is None:
+        candidate = Path(requested_text).expanduser()
+        if candidate.exists():
+            resolved = str(candidate.resolve())
+    if not resolved:
+        report["errorCode"] = "adapter-not-found"
+        report["message"] = "The requested browser adapter could not be resolved."
+        return report
+
+    path = Path(resolved)
+    report["checks"]["resolved"] = True
+    report["adapter"]["name"] = _safe_name(path)
+    report["adapter"]["resolvedPathFingerprint"] = _path_fingerprint(str(path.resolve()))
+    if not path.is_file():
+        report["errorCode"] = "adapter-not-file"
+        report["message"] = "The resolved browser adapter is not a regular executable file."
+        report["fallback"] = _guidance("incompatible")
+        report["status"] = "incompatible"
+        return report
+    report["checks"]["regularFile"] = True
+    if not os.access(path, os.X_OK):
+        report["errorCode"] = "adapter-not-executable"
+        report["message"] = "The resolved browser adapter is not executable."
+        report["fallback"] = _guidance("incompatible")
+        report["status"] = "incompatible"
+        return report
+    report["checks"]["executable"] = True
+    try:
+        completed = subprocess.run(
+            [str(path), "--help"],
+            capture_output=True,
+            text=True,
+            timeout=HELP_TIMEOUT_SECONDS,
+            check=False,
+        )
+    except (OSError, subprocess.TimeoutExpired):
+        completed = None
+    help_text = "" if completed is None else (completed.stdout + "\n" + completed.stderr).lower()
+    if completed is None or completed.returncode != 0 or not help_text:
+        report["errorCode"] = "adapter-help-failed"
+        report["message"] = "The browser adapter did not provide a usable --help response."
+        report["fallback"] = _guidance("incompatible")
+        report["status"] = "incompatible"
+        return report
+    report["checks"]["help"] = True
+    missing = [command for command in REQUIRED_COMMANDS if command not in help_text]
+    report["missingCommands"] = missing
+    if missing:
+        report["errorCode"] = "adapter-command-contract-mismatch"
+        report["message"] = "The browser adapter does not expose Maggie's required command contract."
+        report["fallback"] = _guidance("incompatible")
+        report["status"] = "incompatible"
+        return report
+    report["checks"]["requiredCommands"] = True
+    report["checks"]["interactionCommands"] = all(command in help_text for command in INTERACTION_COMMANDS)
+    if not report["checks"]["interactionCommands"]:
+        report["errorCode"] = "adapter-interaction-contract-mismatch"
+        report["message"] = "The browser adapter can audit pages but cannot replay the interaction contract."
+        report["fallback"] = _guidance("incompatible")
+        report["status"] = "incompatible"
+        return report
+    report["status"] = "ready"
+    report["message"] = "Browser adapter capability preflight passed."
+    report["fallback"] = []
+    return report
+
+
+def require_browser_adapter(requested: str | Path) -> dict:
+    report = discover_browser_adapter(requested)
+    if report["status"] != "ready":
+        code = report.get("errorCode", "adapter-unavailable")
+        message = report.get("message", "Browser adapter is unavailable.")
+        guidance = " ".join(report.get("fallback", []))
+        raise ValueError(f"{code}: {message} {guidance}".strip())
+    return report

package/bundled-tools/runtime/external_write.py

@@ -0,0 +1,122 @@
+"""Validate bounded, hash-only evidence for an external provider write."""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+from urllib.parse import urlsplit
+
+
+SCHEMA = "maggie-external-write-readback.v1"
+PROVIDERS = {"ga4", "gtm", "gsc", "google-ads", "firebase"}
+STATUSES = {"created", "updated", "no-op"}
+FINGERPRINT = re.compile(r"^sha256:[0-9a-f]{64}$")
+
+
+def _safe_text(value: Any, field: str, errors: list[str], pattern: str | None = None) -> str | None:
+    if not isinstance(value, str) or not value.strip() or len(value) > 200 or "@" in value or re.search(r"(?:token|secret|password|BEGIN PRIVATE)", value, re.I):
+        errors.append(f"{field} must be a bounded redacted identifier")
+        return None
+    if pattern and not re.fullmatch(pattern, value):
+        errors.append(f"{field} has an invalid format")
+        return None
+    return value
+
+
+def validate(value: Any) -> dict[str, Any]:
+    errors: list[str] = []
+    if not isinstance(value, dict):
+        return {"schemaVersion": "maggie-external-write-readback-result.v1", "passed": False, "errors": ["evidence must be an object"], "mutation": "not executed"}
+    if value.get("schemaVersion") != SCHEMA:
+        errors.append(f"schemaVersion must be {SCHEMA}")
+    if value.get("provider") not in PROVIDERS:
+        errors.append("provider is unsupported")
+    _safe_text(value.get("generatedAt"), "generatedAt", errors)
+    resource = _safe_text(value.get("resource"), "resource", errors)
+    _safe_text(value.get("operation"), "operation", errors, r"[a-z][a-z0-9_.-]{1,63}")
+    key = _safe_text(value.get("idempotencyKey"), "idempotencyKey", errors, r"[A-Za-z0-9][A-Za-z0-9_.:-]{2,127}")
+
+    retry = value.get("retry")
+    if not isinstance(retry, dict) or set(retry) != {"attempt", "maxAttempts", "sameKeyOnRetry"}:
+        errors.append("retry must contain attempt, maxAttempts, and sameKeyOnRetry")
+        retry = {}
+    else:
+        attempt, maximum = retry.get("attempt"), retry.get("maxAttempts")
+        if not isinstance(attempt, int) or not 1 <= attempt <= 3:
+            errors.append("retry.attempt must be between 1 and 3")
+        if not isinstance(maximum, int) or not 1 <= maximum <= 3 or (isinstance(attempt, int) and isinstance(maximum, int) and attempt > maximum):
+            errors.append("retry.maxAttempts must be between attempt and 3")
+        if retry.get("sameKeyOnRetry") is not True:
+            errors.append("retry.sameKeyOnRetry must be true")
+
+    mutation = value.get("mutation")
+    if not isinstance(mutation, dict) or set(mutation) != {"status", "statusCode", "explicitConfirmation"}:
+        errors.append("mutation must contain status, statusCode, and explicitConfirmation")
+        mutation = {}
+    else:
+        if mutation.get("status") not in STATUSES:
+            errors.append("mutation.status is unsupported")
+        if not isinstance(mutation.get("statusCode"), int) or not 200 <= mutation["statusCode"] <= 299:
+            errors.append("mutation.statusCode must be a successful HTTP status")
+        if mutation.get("explicitConfirmation") is not True:
+            errors.append("mutation requires explicit confirmation")
+    if value.get("mutationExecuted") is not True:
+        errors.append("mutationExecuted must be true")
+
+    readback = value.get("readback")
+    safe_checks: list[dict[str, Any]] = []
+    if not isinstance(readback, dict) or set(readback) != {"passed", "endpoint", "checks"}:
+        errors.append("readback must contain passed, endpoint, and checks")
+        readback = {}
+    else:
+        if readback.get("passed") is not True:
+            errors.append("readback.passed must be true")
+        endpoint = readback.get("endpoint")
+        parsed = urlsplit(endpoint) if isinstance(endpoint, str) else None
+        if not parsed or parsed.scheme != "https" or not parsed.netloc or parsed.query or parsed.fragment or parsed.username or parsed.password:
+            errors.append("readback.endpoint must be an HTTPS URL without credentials/query")
+        checks = readback.get("checks")
+        if not isinstance(checks, list) or not checks:
+            errors.append("readback.checks must be a non-empty array")
+            checks = []
+        for index, check in enumerate(checks):
+            prefix = f"readback.checks[{index}]"
+            if not isinstance(check, dict) or set(check) != {"name", "expectedFingerprint", "observedFingerprint", "passed"}:
+                errors.append(f"{prefix} must contain name and hash-only invariant fields")
+                continue
+            name = _safe_text(check.get("name"), f"{prefix}.name", errors)
+            expected = check.get("expectedFingerprint")
+            observed = check.get("observedFingerprint")
+            if not isinstance(expected, str) or not FINGERPRINT.fullmatch(expected):
+                errors.append(f"{prefix}.expectedFingerprint must be sha256")
+            if not isinstance(observed, str) or not FINGERPRINT.fullmatch(observed):
+                errors.append(f"{prefix}.observedFingerprint must be sha256")
+            if check.get("passed") is not True or expected != observed:
+                errors.append(f"{prefix} does not match its expected readback")
+            safe_checks.append({"name": name, "passed": check.get("passed") is True})
+
+    duplicates = value.get("duplicates")
+    orphaned = value.get("orphaned")
+    if not isinstance(duplicates, list) or duplicates:
+        errors.append("duplicates must be an empty array after reconciliation")
+    if not isinstance(orphaned, list) or orphaned:
+        errors.append("orphaned must be an empty array after cleanup")
+    cleanup = value.get("cleanup")
+    if not isinstance(cleanup, dict) or set(cleanup) != {"status", "checked"} or cleanup.get("status") not in {"not-needed", "passed"} or cleanup.get("checked") is not True:
+        errors.append("cleanup must be checked and not-needed or passed")
+
+    return {
+        "schemaVersion": "maggie-external-write-readback-result.v1",
+        "passed": not errors,
+        "errors": sorted(set(errors)),
+        "provider": value.get("provider"),
+        "resource": resource,
+        "operation": value.get("operation"),
+        "idempotencyKey": key,
+        "retry": {"attempt": retry.get("attempt"), "maxAttempts": retry.get("maxAttempts"), "sameKeyOnRetry": retry.get("sameKeyOnRetry") is True},
+        "readback": {"passed": readback.get("passed") is True, "checks": safe_checks} if isinstance(readback, dict) else {"passed": False, "checks": []},
+        "duplicates": [],
+        "orphaned": [],
+        "cleanup": cleanup if isinstance(cleanup, dict) else {},
+        "mutation": "not executed",
+    }

package/bundled-tools/runtime/google_capabilities.py

@@ -7,7 +7,7 @@ from typing import Any
 from urllib.parse import urlsplit
 
 
-SCHEMA_VERSION = "maggie-google-capability-report.v1"
+SCHEMA_VERSION = "maggie-google-capability-report.v2"
 CAPABILITY_NAMES = ("read", "report", "edit", "publish")
 CAPABILITY_STATES = {"verified", "not_tested", "not_available", "blocked"}
 PROVIDERS = {"gsc", "ga4", "gtm", "google-ads", "firebase"}
@@ -112,6 +112,34 @@ def _write_test(value: Any, field: str, errors: list[str]) -> bool:
     return valid and not unknown
 
 
+def _verified_reference(value: Any, field: str, errors: list[str]) -> dict[str, Any]:
+    if not isinstance(value, dict) or set(value) != {"id", "verified"}:
+        errors.append(f"{field} must contain only id and verified")
+        return {"id": None, "verified": False}
+    identifier = value.get("id")
+    if not isinstance(identifier, str) or not identifier.strip() or len(identifier) > 200 or re.search(r"[@\s]", identifier):
+        errors.append(f"{field}.id must be a redacted non-email identifier")
+    if value.get("verified") is not True:
+        errors.append(f"{field}.verified must be true")
+    return {"id": identifier if isinstance(identifier, str) else None, "verified": value.get("verified") is True}
+
+
+def _target_reference(value: Any, resource: str, field: str, errors: list[str]) -> dict[str, Any]:
+    if not isinstance(value, dict) or set(value) != {"id", "kind", "verified"}:
+        errors.append(f"{field} must contain only id, kind, and verified")
+        return {"id": None, "kind": None, "verified": False}
+    identifier = value.get("id")
+    if not isinstance(identifier, str) or not identifier.strip() or len(identifier) > 200 or re.search(r"[@\s]", identifier):
+        errors.append(f"{field}.id must be a redacted non-email identifier")
+    if identifier != resource:
+        errors.append(f"{field}.id must equal the selected resource")
+    if value.get("kind") not in {"property", "container", "customer", "project", "site", "account"}:
+        errors.append(f"{field}.kind is unsupported")
+    if value.get("verified") is not True:
+        errors.append(f"{field}.verified must be true")
+    return {"id": identifier if isinstance(identifier, str) else None, "kind": value.get("kind"), "verified": value.get("verified") is True}
+
+
 def _required_scope(provider: str, capability: str) -> str | None:
     if capability == "read" or capability == "report":
         return READ_SCOPES[provider]
@@ -124,9 +152,9 @@ def validate_report(report: Any) -> dict[str, Any]:
     """Return safe validation output; never returns arbitrary input fields."""
     errors: list[str] = []
     if not isinstance(report, dict):
-        return {"schemaVersion": "maggie-google-capability-report-result.v1", "passed": False, "errors": ["report must be an object"], "providerResults": []}
+        return {"schemaVersion": "maggie-google-capability-report-result.v2", "passed": False, "errors": ["report must be an object"], "providerResults": []}
     if report.get("schemaVersion") != SCHEMA_VERSION:
-        errors.append("schemaVersion must be maggie-google-capability-report.v1")
+        errors.append("schemaVersion must be maggie-google-capability-report.v2; v1 reports lack target guard evidence")
     if not _string(report.get("generatedAt"), "generatedAt", errors):
         pass
     if report.get("mutationsAllowed") is not False:
@@ -143,7 +171,7 @@ def validate_report(report: Any) -> dict[str, Any]:
         if not isinstance(row, dict):
             errors.append(f"{prefix} must be an object")
             continue
-        required = {"provider", "resource", "authMode", "scopes", "productRole", "evidence", "capabilities", "nextAction"}
+        required = {"provider", "resource", "activeAccount", "target", "authMode", "scopes", "productRole", "evidence", "capabilities", "nextAction"}
         unknown = sorted(set(row) - required)
         if unknown:
             errors.append(f"{prefix} contains unsupported fields")
@@ -154,6 +182,8 @@ def validate_report(report: Any) -> dict[str, Any]:
             continue
         if not _string(resource, f"{prefix}.resource", errors, max_length=200):
             continue
+        active_account = _verified_reference(row.get("activeAccount"), f"{prefix}.activeAccount", errors)
+        target = _target_reference(row.get("target"), resource, f"{prefix}.target", errors)
         key = (provider, resource)
         if key in seen:
             errors.append(f"{prefix} duplicates provider/resource")
@@ -226,6 +256,8 @@ def validate_report(report: Any) -> dict[str, Any]:
         normalized.append({
             "provider": provider,
             "resource": resource,
+            "activeAccount": active_account,
+            "target": target,
             "authMode": row.get("authMode"),
             "scopes": sorted(scopes),
             "productRole": row.get("productRole"),
@@ -241,7 +273,7 @@ def validate_report(report: Any) -> dict[str, Any]:
         })
 
     return {
-        "schemaVersion": "maggie-google-capability-report-result.v1",
+        "schemaVersion": "maggie-google-capability-report-result.v2",
         "passed": not errors,
         "errors": sorted(set(errors)),
         "providerResults": normalized,

package/package.json

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

package/references/browser-inspection.md

@@ -14,6 +14,23 @@ The browser capability must support:
 - slow scrolling, click, hover, keyboard focus, and back/forward navigation;
 - reading computed CSS, media sources, links, and visible accessibility labels.
 
+Before navigation, Maggie runs a capability preflight against the configured
+adapter. The report is `maggie-browser-capability.v1` and classifies the
+adapter as `ready`, `missing`, or `incompatible`. This prevents a system
+`browse`/`xdg-open` desktop opener from being mistaken for a browser adapter:
+
+```bash
+maggie browser-audit https://example.com \
+  --browse "$HOME/.codex/skills/gstack/browse/dist/browse" \
+  --output .maggie/browser-audit --required body --check-browser
+```
+
+The report contains only the adapter name, path fingerprints, capability
+checks, and bounded installation/fallback guidance. If it is `missing` or
+`incompatible`, install or enable an authorized Chrome/Playwright/gstack
+adapter and pass its executable path. Maggie does not silently install a
+browser runtime or use a desktop opener as a fallback.
+
 The minimum extraction result for a target is:
 
 ```text

package/references/google-integrations-runbook.md

@@ -111,8 +111,13 @@ maggie ops google-capabilities \
 ```
 
 The report contract is
-[`capability-report-v1.json`](../bundled-contracts/google-integrations/capability-report-v1.json).
+[`capability-report-v2.schema.json`](../bundled-contracts/google-integrations/capability-report-v2.schema.json).
 The CLI writes a normalized result and never copies arbitrary input fields.
+Every provider row must also identify the redacted active account and selected
+target resource, both with `verified: true`; the target ID must equal the
+selected `resource`. A report that only proves account discovery, or comes from
+the wrong browser account/property, is rejected before a write workflow can use
+it.
 
 ## Capability matrix
 
@@ -121,6 +126,8 @@ Every provider/resource row must expose this shape:
 | Field | Meaning |
 |---|---|
 | `provider` / `resource` | The Google product and scoped resource being checked |
+| `activeAccount` | Redacted account/principal reference confirmed by the current auth session |
+| `target` | Resource ID and kind confirmed in the current account; must match `resource` |
 | `authMode` | `desktop-oauth`, `service-account-impersonation`, or `none` |
 | `scopes` | Exact allowlisted OAuth scopes, never token values |
 | `productRole` | Role granted in the product, distinct from Cloud IAM |