@topy-ai/maggie 0.7.31 → 0.7.33

package/bundled-tools/clis/site_audit.py

@@ -9,7 +9,7 @@ import json
 import re
 import sys
 from pathlib import Path
-from urllib.parse import urljoin, urlparse
+from urllib.parse import urljoin, urlparse, urlunparse
 from html.parser import HTMLParser
 from urllib.request import Request, urlopen
 
@@ -233,7 +233,16 @@ def hreflang_check(url: str, page: PageParser, expected: set[str]) -> dict:
     return {"ok": not missing and not reciprocal_errors, "missing": missing, "reciprocal_errors": reciprocal_errors, "links": links}
 
 
-def sitemap_urls(base: str) -> tuple[list[str], list[dict[str, str]]]:
+def sitemap_target(base: str, value: str, *, preserve_origin: bool = False) -> str:
+    """Resolve a sitemap loc while keeping crawl traffic on the requested origin."""
+    parsed = urlparse(value)
+    if preserve_origin or not parsed.scheme or not parsed.netloc:
+        return urljoin(base + "/", value)
+    requested = urlparse(base)
+    return urlunparse((requested.scheme, requested.netloc, parsed.path or "/", "", parsed.query, ""))
+
+
+def sitemap_urls(base: str, *, preserve_origin: bool = False) -> tuple[list[str], list[dict[str, str]]]:
     """Resolve a sitemap index and return page URLs plus raw loc violations."""
     pending = [urljoin(base + "/", "sitemap.xml")]
     pages = []
@@ -249,7 +258,7 @@ def sitemap_urls(base: str) -> tuple[list[str], list[dict[str, str]]]:
         for value in raw_locs:
             if not re.match(r"^https?://[^\s]+$", value, re.I):
                 violations.append({"sitemap": sitemap_url, "loc": value, "reason": "sitemap loc must be an absolute HTTP(S) URL"})
-        locs = [urljoin(base + "/", value) for value in raw_locs]
+        locs = [sitemap_target(base, value, preserve_origin=preserve_origin) for value in raw_locs]
         if re.search(r"<sitemapindex\b", body, re.I):
             pending.extend(locs)
         else:
@@ -280,9 +289,13 @@ def main() -> int:
     parser.add_argument("--check-translation-completeness", action="store_true")
     parser.add_argument("--access-log", type=Path, help="optional local access log for crawler-request diagnosis")
     parser.add_argument("--require-sitemap-request", action="store_true", help="fail unless the supplied access log contains a sitemap request")
+    parser.add_argument("--preserve-sitemap-origin", action="store_true", help="opt in to crawling absolute sitemap URLs on their declared origins")
     baseline_args = parser.add_mutually_exclusive_group()
     baseline_args.add_argument("--save-baseline", type=Path, help="create a new reviewed contract from a passing complete crawl")
     baseline_args.add_argument("--baseline", type=Path, help="fail on differences from a reviewed contract")
+    parser.add_argument("--recapture-baseline", type=Path, help="write a reviewed versioned baseline after reviewing every drift")
+    parser.add_argument("--baseline-id", help="required stable ID for --recapture-baseline")
+    parser.add_argument("--reason", action="append", default=[], metavar="URL=REASON", help="reviewer-approved reason for one drifting URL; repeat for every drift")
     parser.add_argument("--reviewer", help="required for --save-baseline")
     args = parser.parse_args()
     if args.max_pages < 1:
@@ -291,6 +304,17 @@ def main() -> int:
         parser.error("baseline operations require --crawl")
     if args.save_baseline and not (args.reviewer or "").strip():
         parser.error("save-baseline requires --reviewer")
+    if args.recapture_baseline:
+        if not args.baseline:
+            parser.error("--recapture-baseline requires --baseline")
+        if not args.crawl:
+            parser.error("baseline recapture requires --crawl")
+        if not (args.reviewer or "").strip():
+            parser.error("baseline recapture requires --reviewer")
+        if not args.baseline_id or not re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9._:-]{0,79}", args.baseline_id):
+            parser.error("baseline recapture requires a safe --baseline-id")
+    if args.save_baseline and args.recapture_baseline:
+        parser.error("--save-baseline cannot be combined with --recapture-baseline")
     try:
         expected_languages = language_set(args.languages)
         markets = {item.strip() for item in (args.markets or "").split(",") if item.strip()}
@@ -349,7 +373,7 @@ def main() -> int:
     crawl = {"enabled": args.crawl, "passed": True, "pages": []}
     if args.crawl:
         try:
-            urls, sitemap_violations = sitemap_urls(base)
+            urls, sitemap_violations = sitemap_urls(base, preserve_origin=args.preserve_sitemap_origin)
             crawl["discovered_url_count"] = len(urls)
             crawl["complete"] = len(urls) <= args.max_pages and not sitemap_violations
             urls = urls[: args.max_pages]
@@ -371,6 +395,8 @@ def main() -> int:
                     page_checks = {"url": page_url, "passed": False, "error": type(exc).__name__}
                 crawl["pages"].append(page_checks)
             crawl["sitemap_loc_violations"] = sitemap_violations
+            crawl["requestedOrigin"] = base
+            crawl["sitemapOriginPolicy"] = "declared-origin" if args.preserve_sitemap_origin else "requested-origin"
             crawl["passed"] = crawl["complete"] and bool(urls) and len(crawl["pages"]) == len(urls) and all(item["passed"] for item in crawl["pages"])
             crawl["url_count"] = len(urls)
         except Exception as exc:
@@ -380,9 +406,56 @@ def main() -> int:
     result["evidence"] = {"structural": "captured", "rendered": "not_run", "behavioral": "not_run"}
     crawl["summary"] = summarize_crawl(crawl["pages"])
     try:
+        current_passed = result["passed"]
         if args.baseline:
-            result["baseline"] = site_baseline.compare(json.loads(args.baseline.read_text()), result)
+            previous_baseline = json.loads(args.baseline.read_text())
+            result["baseline"] = site_baseline.compare(previous_baseline, result)
             result["passed"] = result["passed"] and result["baseline"]["passed"]
+            if args.recapture_baseline:
+                comparison = result["baseline"]
+                drift_urls = set(comparison.get("added", [])) | set(comparison.get("removed", []))
+                drift_urls |= {item["url"] for item in comparison.get("changed", []) if isinstance(item, dict) and item.get("url")}
+                drift_urls |= {item["url"] for item in comparison.get("contentChanged", []) if isinstance(item, dict) and item.get("url")}
+                reasons: dict[str, str] = {}
+                for value in args.reason:
+                    url, separator, reason = value.partition("=")
+                    if not separator or not url.strip() or not reason.strip():
+                        raise ValueError("each --reason must use URL=REASON")
+                    url = url.strip()
+                    if url in reasons:
+                        raise ValueError("duplicate baseline change reason")
+                    if url not in drift_urls:
+                        raise ValueError("baseline change reason references a URL without a detected drift")
+                    reasons[url] = reason.strip()
+                missing_reasons = sorted(drift_urls - reasons.keys())
+                if missing_reasons:
+                    raise ValueError("every drifting URL requires a reviewer reason")
+                if not current_passed:
+                    raise ValueError("baseline recapture requires a passing current crawl")
+                recapture_report = dict(result)
+                # The comparison intentionally makes the aggregate result
+                # fail while the current crawl itself is still valid. Snapshot
+                # validates the latter, not whether the old baseline drifted.
+                recapture_report["passed"] = current_passed
+                recaptured = site_baseline.snapshot(
+                    recapture_report,
+                    args.reviewer,
+                    baseline_id=args.baseline_id,
+                    supersedes=previous_baseline.get("baselineId") or site_baseline.baseline_fingerprint(previous_baseline),
+                    change_reasons=reasons,
+                )
+                site_baseline.save(args.recapture_baseline, recaptured)
+                result["baselineRecapture"] = {
+                    "passed": True,
+                    "saved": str(args.recapture_baseline),
+                    "baselineId": args.baseline_id,
+                    "supersedes": recaptured["supersedes"],
+                    "reasonCount": len(reasons),
+                }
+                # A reviewed recapture resolves the old-baseline diff; the
+                # command's exit status should reflect the current crawl and
+                # the completed review gate.
+                result["passed"] = current_passed
         if args.save_baseline:
             site_baseline.save(args.save_baseline, site_baseline.snapshot(result, args.reviewer))
             result["baseline"] = {"passed": True, "saved": str(args.save_baseline)}

package/bundled-tools/integrations/analytics.md

@@ -25,6 +25,26 @@ booking click is only an outbound intent signal; it is not a confirmed booking
 or revenue event. Add conversion events only when the host project defines a
 verified provider callback or reconciliation source.
 
+## Consent ordering and first-party scope
+
+Consent Mode is an ordering contract, not only a boolean configuration:
+
+1. Push the default consent state inline into the data layer before loading the
+   tag manager/container snippet.
+2. Let vendor tags follow Consent Mode. Do not remove the default data-layer
+   event merely because analytics is disabled before consent.
+3. Stop first-party analytics storage when consent is denied, or declare and
+   evidence an explicit degraded mode. Do not silently keep identifiers.
+4. Treat an intentional first-party form submission as a separate privacy
+   decision. If it is recorded without analytics consent, declare
+   `intentionalFormMode: "record"` in the contract and document the lawful
+   basis and retention policy in the host project; otherwise use `"omit"`.
+
+The release contract must declare `defaultBeforeContainer`,
+`firstPartyStorageMode` (`stop` or `degrade`), and `intentionalFormMode`
+(`record` or `omit`). Browser evidence must prove the ordering and the
+first-party behavior; a missing observation is `unknown`, never `false`.
+
 ## GSC
 
 Prefer DNS verification for production. If HTML verification is needed, use a

package/bundled-tools/runtime/maggie_blog_publish.py

@@ -0,0 +1,38 @@
+"""Validate an explicit, evidence-backed automatic blog publication opt-in."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+REQUIRED = ("localeVariants", "featureImage", "seo", "sitemap", "indexingNotification", "audit")
+
+
+def validate_auto_publish(value: object) -> dict[str, Any]:
+    errors: list[str] = []
+    if not isinstance(value, dict):
+        return {"schemaVersion": "maggie-blog-auto-publish-result.v1", "passed": False, "errors": ["evidence must be an object"], "mutation": "not executed"}
+    if value.get("schemaVersion") != "maggie-blog-auto-publish.v1":
+        errors.append("schemaVersion must be maggie-blog-auto-publish.v1")
+    if value.get("optIn") is not True:
+        errors.append("optIn must be true for automatic publishing")
+    if value.get("requireReview") is not False or value.get("reviewDisabledExplicitly") is not True:
+        errors.append("automatic publishing requires explicit review disablement")
+    checks: dict[str, bool] = {}
+    for name in REQUIRED:
+        item = value.get(name)
+        passed = isinstance(item, dict) and item.get("passed") is True
+        checks[name] = passed
+        if not passed:
+            errors.append(f"{name}.passed must be true")
+    return {
+        "schemaVersion": "maggie-blog-auto-publish-result.v1",
+        "passed": not errors,
+        "errors": sorted(set(errors)),
+        "optIn": value.get("optIn") is True,
+        "requireReview": value.get("requireReview"),
+        "reviewDisabledExplicitly": value.get("reviewDisabledExplicitly") is True,
+        "checks": checks,
+        "mutation": "not executed",
+        "nextAction": "host may call its explicit publish path only after this gate passes" if not errors else "keep content in human review",
+    }

package/bundled-tools/runtime/maggie_dash_panels.py

@@ -0,0 +1,111 @@
+"""Validate source and freshness evidence for independent dashboard panels."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any
+
+
+SCHEMA = "maggiedash-measurement-panels.v1"
+MODES = {"live", "snapshot"}
+STATUSES = {"pass", "stale", "error"}
+
+
+def _timestamp(value: object) -> bool:
+    if not isinstance(value, str) or not value.strip():
+        return False
+    try:
+        datetime.fromisoformat(value.replace("Z", "+00:00"))
+    except ValueError:
+        return False
+    return True
+
+
+def validate_panel_report(value: object) -> dict[str, Any]:
+    errors: list[str] = []
+    warnings: list[str] = []
+    normalized: list[dict[str, Any]] = []
+    if not isinstance(value, dict):
+        return {"schemaVersion": SCHEMA, "passed": False, "errors": ["report must be an object"], "panels": [], "failedPanels": [], "warnings": []}
+    if value.get("schemaVersion") != SCHEMA:
+        errors.append(f"schemaVersion must be {SCHEMA}")
+    panels = value.get("panels")
+    if not isinstance(panels, list) or not panels:
+        errors.append("panels must be a non-empty list")
+        panels = []
+    seen: set[str] = set()
+    failed: list[str] = []
+    for index, panel in enumerate(panels):
+        at = f"panels[{index}]"
+        if not isinstance(panel, dict):
+            errors.append(f"{at} must be an object")
+            continue
+        panel_id = panel.get("id")
+        if not isinstance(panel_id, str) or not panel_id.strip():
+            errors.append(f"{at}.id must be a non-empty string")
+            panel_id = f"panel-{index}"
+        if panel_id in seen:
+            errors.append(f"{at}.id is duplicated")
+        seen.add(panel_id)
+        source = panel.get("source")
+        source_name = ""
+        if isinstance(source, dict):
+            source_name = str(source.get("name") or source.get("system") or "").strip()
+        elif isinstance(source, str):
+            source_name = source.strip()
+        if not source_name:
+            errors.append(f"{at}.source must identify a data source")
+        mode = panel.get("mode")
+        if mode not in MODES:
+            errors.append(f"{at}.mode must be live or snapshot")
+        observed_at = panel.get("observedAt")
+        if not _timestamp(observed_at):
+            errors.append(f"{at}.observedAt must be an ISO-8601 timestamp")
+        max_age = panel.get("maxAgeSeconds")
+        if not isinstance(max_age, int) or isinstance(max_age, bool) or max_age < 1:
+            errors.append(f"{at}.maxAgeSeconds must be a positive integer")
+            max_age = 0
+        age = panel.get("ageSeconds")
+        if not isinstance(age, int) or isinstance(age, bool) or age < 0:
+            errors.append(f"{at}.ageSeconds must be a non-negative integer")
+            age = 0
+        status = panel.get("status")
+        if status not in STATUSES:
+            errors.append(f"{at}.status must be pass, stale, or error")
+            status = "error"
+        warning = str(panel.get("warning") or "").strip()
+        error = panel.get("error")
+        if status == "stale":
+            if not warning:
+                errors.append(f"{at}.warning is required for stale panels")
+            warnings.append(panel_id)
+        if status == "error":
+            failed.append(panel_id)
+            if not isinstance(error, dict) or not str(error.get("code") or "").strip() or not str(error.get("remediation") or "").strip():
+                errors.append(f"{at}.error requires a code and remediation")
+        if status == "stale" or status == "error":
+            failed.append(panel_id)
+        if status == "pass" and age > max_age:
+            errors.append(f"{at}.status cannot be pass when ageSeconds exceeds maxAgeSeconds")
+            failed.append(panel_id)
+        normalized.append({
+            "id": panel_id,
+            "source": source_name,
+            "mode": mode,
+            "observedAt": observed_at,
+            "maxAgeSeconds": max_age,
+            "ageSeconds": age,
+            "status": status,
+            "warning": bool(warning),
+            "errorCode": str(error.get("code")) if isinstance(error, dict) and error.get("code") else None,
+        })
+    failed = sorted(set(failed))
+    return {
+        "schemaVersion": "maggiedash-measurement-panels-result.v1",
+        "passed": not errors and not failed and bool(normalized),
+        "errors": sorted(set(errors)),
+        "panels": normalized,
+        "failedPanels": failed,
+        "warnings": sorted(set(warnings)),
+        "mutation": "not executed",
+    }

package/bundled-tools/runtime/maggie_quality.py

@@ -244,7 +244,7 @@ def validate_reconcile_contract(contract: object) -> dict[str, Any]:
     if contract.get("writesOnlyWhenChanged") is not True:
         errors.append("writesOnlyWhenChanged must be true")
     report = contract.get("report") if isinstance(contract.get("report"), dict) else {}
-    for key in ("changed", "unchanged"):
+    for key in ("changed", "unchanged", "writes"):
         if report.get(key) is not True:
             errors.append(f"report.{key} evidence is required")
     second = contract.get("secondRun") if isinstance(contract.get("secondRun"), dict) else {}

package/bundled-tools/runtime/maggie_sections.py

@@ -430,4 +430,42 @@ def reconcile_fields(current: object, desired: object) -> dict[str, Any]:
         else:
             result[key] = copy.deepcopy(value)
             changed.append(str(key))
-    return {"schemaVersion": RECONCILE_SCHEMA, "passed": True, "changed": changed, "alreadyCorrect": already_correct, "result": result, "convergent": True}
+    return {
+        "schemaVersion": RECONCILE_SCHEMA,
+        "passed": True,
+        "changed": changed,
+        "alreadyCorrect": already_correct,
+        "writeCount": len(changed),
+        "unchangedCount": len(already_correct),
+        "writeOutcome": {"wrote": bool(changed), "reason": "changed-fields" if changed else "already-correct"},
+        "result": result,
+        "convergent": True,
+    }
+
+
+def summarize_write_outcomes(outcomes: object) -> dict[str, Any]:
+    """Summarize step-level compare-and-set outcomes by actual writes.
+
+    A step is not a write. Callers must report a boolean ``wrote`` outcome so
+    a successful no-op cannot inflate release or migration write counts.
+    """
+    if not isinstance(outcomes, list) or not outcomes:
+        return {"schemaVersion": "maggiedash-write-outcomes.v1", "passed": False, "errors": ["outcomes must be a non-empty list"]}
+    errors: list[str] = []
+    normalized: list[dict[str, Any]] = []
+    for index, outcome in enumerate(outcomes):
+        if not isinstance(outcome, dict) or not isinstance(outcome.get("wrote"), bool):
+            errors.append(f"outcomes[{index}].wrote must be boolean")
+            continue
+        normalized.append({"step": str(outcome.get("step") or index), "wrote": outcome["wrote"]})
+    writes = sum(1 for item in normalized if item["wrote"])
+    return {
+        "schemaVersion": "maggiedash-write-outcomes.v1",
+        "passed": not errors,
+        "errors": errors,
+        "steps": len(normalized),
+        "writes": writes,
+        "unchanged": len(normalized) - writes,
+        "outcomes": normalized,
+        "convergent": not errors,
+    }

package/bundled-tools/runtime/site_baseline.py

@@ -2,12 +2,26 @@
 from __future__ import annotations
 
 import json
+import hashlib
 from datetime import datetime, timezone
 from pathlib import Path
 from urllib.parse import urlparse
 
 
-def snapshot(report: dict, reviewer: str) -> dict:
+def baseline_fingerprint(baseline: dict) -> str:
+    """Return a stable identity for legacy baselines without baselineId."""
+    encoded = json.dumps(baseline, sort_keys=True, ensure_ascii=False, separators=(",", ":")).encode()
+    return "sha256:" + hashlib.sha256(encoded).hexdigest()[:16]
+
+
+def snapshot(
+    report: dict,
+    reviewer: str,
+    *,
+    baseline_id: str | None = None,
+    supersedes: str | None = None,
+    change_reasons: dict[str, str] | None = None,
+) -> dict:
     if not reviewer.strip():
         raise ValueError("baseline requires a reviewer")
     crawl = report.get("crawl", {})
@@ -32,10 +46,17 @@ def snapshot(report: dict, reviewer: str) -> dict:
             content[page["url"]] = page["contentContract"]
     if not contracts:
         raise ValueError("baseline has no non-query page contracts")
-    return {"schemaVersion": "maggie-site-baseline.v1", "url": report["url"],
+    result = {"schemaVersion": "maggie-site-baseline.v1", "url": report["url"],
             "reviewer": reviewer.strip(), "createdAt": datetime.now(timezone.utc).isoformat(),
             "pages": contracts, "content": content,
             "excludedQueryUrls": sorted(excluded_query_urls)}
+    if baseline_id:
+        result["baselineId"] = baseline_id
+    if supersedes:
+        result["supersedes"] = supersedes
+    if change_reasons:
+        result["approvedChangeReasons"] = {key: change_reasons[key] for key in sorted(change_reasons)}
+    return result
 
 
 def compare(baseline: dict, report: dict) -> dict:

package/package.json

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

package/references/google-integrations-runbook.md

@@ -52,6 +52,32 @@ The validator accepts the complete provider allowlist, but a capability is
 verified only when its corresponding required scope is present. Scope presence
 alone never proves product access.
 
+### GTM operation scope matrix
+
+Request the union of the rows needed by one operation; do not use a broad
+scope merely because a later operation might need it:
+
+| GTM operation | Minimum OAuth scope |
+|---|---|
+| List/read account, container, tag, trigger, or variable | `https://www.googleapis.com/auth/tagmanager.readonly` |
+| Edit container configuration | `https://www.googleapis.com/auth/tagmanager.edit.containers` |
+| Create or update a container version | `https://www.googleapis.com/auth/tagmanager.edit.containerversions` |
+| Publish a container version | `https://www.googleapis.com/auth/tagmanager.publish` |
+
+An operation that edits a container and creates a version must request both
+edit scopes; publishing additionally requires the publish scope. Record the
+operation name and exact scope union in the capability evidence so a successful
+read cannot be mistaken for edit or publish access.
+
+### Missing fields are unknown
+
+Google APIs can omit fields, especially when a proto3 field is absent from the
+response or was not selected by the request. An omitted boolean is not
+`false`, and an absent schema field is not evidence that the capability is
+disabled. Reports must use `unknown`/`not_observed` in the provider adapter's
+evidence and obtain a corroborating read or time-series observation before
+making a negative claim. Never silently coerce a missing field to `false`.
+
 ## Provider setup and read-only preflight
 
 1. Select one provider and one resource. Enable only that provider API in the