@topy-ai/maggie 0.7.30 → 0.7.32

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

@@ -68,6 +68,22 @@ cannot render the icon, add an approved runtime definition or inline SVG
 fallback and rerun both checks. Never release a source token solely because
 typecheck or build succeeded.
 
+Compose the static inventory with browser-painted evidence before declaring a
+design release complete:
+
+```bash
+maggie design icon-release-gate \
+  --icon-report docs/icon-inventory.json \
+  --browser-report .maggie/icon-browser-evidence.json \
+  --output docs/icon-release-gate.json
+```
+
+The browser evidence must use `maggie-icon-browser-evidence.v1`, include at
+least one route, and report each glyph as visible with positive dimensions,
+a successful `assetStatus` (2xx), and a non-empty accessible name. This
+gate is independent from typecheck/build and is read-only apart from its
+explicit output.
+
 ## Automatic memory hook
 
 Follow [Maggie Memory Hook](../../references/memory-hook.md) at invocation and completion.

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

@@ -57,8 +57,17 @@ fields and supplies the normal `type`, `summary`, `expected`, `actual`,
 `errorFingerprint`, reproduction, resolution, validation, and screenshot
 metadata fields. It may also provide bounded `routeIds` and
 `validationEvidence` identifiers. Each generated draft stores only the safe
-batch ID, zero-based index, and bounded size. The batch command still creates
-local drafts only.
+batch ID, canonical zero-based index, and bounded size. Direct `collect` calls
+use zero-based `--batch-index` by default. If an external runner reports
+one-based positions, pass `--batch-base 1`; the final item is then accepted and
+normalized before it is stored. The batch command still creates local drafts
+only.
+
+For example, the third item in a three-item, one-based batch is collected as:
+
+    maggie feedback collect --project . --batch-id run-review-001 \
+      --batch-index 3 --batch-size 3 --batch-base 1 \
+      --summary "Final item" --type bug
 
 Aggregate a batch before manual review:
 

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

@@ -187,8 +187,17 @@ npx @topy-ai/maggie update --project .
 ```
 
 Use `--force` only after the user explicitly approves replacing locally
-modified managed files. An npm skill update does not automatically deploy the
-dashboard or migrate a production database.
+modified managed files. The update output reports preserved files and a bounded
+diff summary for text files so the operator can distinguish stale package
+content from a project customization before choosing `--force`. It never
+publishes the full local file or secrets. An npm skill update does not
+automatically deploy the dashboard or migrate a production database.
+
+`maggie doctor` reports the managed skill inventory without changing files. If
+the manifest and on-disk skill names disagree, it prints the missing or extra
+names and exits non-zero; resolve that mismatch before continuing with a
+mutation. A diagnostic result without an installed manifest does not claim
+that bootstrap is complete.
 
 ### Verify
 

package/bundled-skills/maggie-seo-geo/SKILL.md

@@ -118,6 +118,22 @@ with a reviewer. Commit the approved change and new contract together; never
 automatically replace the baseline following failure. Dynamic dates, class
 names and copy can produce legitimate differences requiring review.
 
+To approve an intentional drift, write a new file and require a reason for
+every changed, added, removed, or content-changed URL:
+
+```bash
+maggie site-audit https://example.com --crawl --json \
+  --baseline docs/seo-baseline-v1.json \
+  --recapture-baseline docs/seo-baseline-v2.json \
+  --baseline-id seo-v2 --reviewer maintainer \
+  --reason 'https://example.com/pricing=approved pricing refresh'
+```
+
+The command fails closed when the current crawl is incomplete, a drift has no
+reason, a reason names a URL without a reported drift, or the destination file
+already exists. The new contract records its `baselineId`, `supersedes` value,
+reviewer, and approved reasons; the old baseline is never overwritten.
+
 This covers server-rendered sitemap pages, not CSS rendering, JavaScript-only
 content, database translation keys or browser interactions. Query-string URLs
 are recorded as excluded from byte baselines because they often represent
@@ -256,7 +272,12 @@ metadata, valid entity JSON-LD, and image alt text. Non-HTML endpoints such as
 RSS must not be included in the HTML page sitemap. Sitemap `<loc>` values must
 be absolute HTTP(S) URLs; the audit reports relative values as a failure even
 when it can resolve them for continued crawling, so one malformed entry cannot
-hide a protocol violation.
+hide a protocol violation. Absolute sitemap locations are rebased to the
+origin passed to `site-audit` by default, so `--crawl` cannot silently audit
+production from a staging/local command. The JSON crawl evidence records
+`requestedOrigin` and `sitemapOriginPolicy: "requested-origin"`. Use
+`--preserve-sitemap-origin` only when an explicitly reviewed cross-origin crawl
+is intended; the report then says `"declared-origin"`.
 Use `--output <project>/docs/site-audit.json` to persist the evidence used by
 the release review.
 

package/bundled-tools/clis/maggie.py

@@ -933,6 +933,13 @@ def command_fixture(args: argparse.Namespace) -> int:
     return 0
 
 
+def command_feedback(args: argparse.Namespace) -> int:
+    """Dispatch feedback subcommands through the canonical feedback CLI."""
+    cli = Path(__file__).with_name("maggie_feedback.py")
+    completed = subprocess.run([sys.executable, str(cli), *args.feedback_args], cwd=Path.cwd(), check=False)
+    return completed.returncode
+
+
 def parser() -> argparse.ArgumentParser:
     p = argparse.ArgumentParser(prog="maggie", description=__doc__)
     sub = p.add_subparsers(dest="command", required=True)
@@ -984,6 +991,9 @@ def parser() -> argparse.ArgumentParser:
         item = fixture_sub.add_parser(fixture_name)
         item.add_argument("project", nargs="?", default=".")
         item.set_defaults(func=command_fixture)
+    feedback = sub.add_parser("feedback", help="collect, review, and submit privacy-safe feedback")
+    feedback.add_argument("feedback_args", nargs=argparse.REMAINDER, help="arguments for maggie_feedback.py")
+    feedback.set_defaults(func=command_feedback)
     doctor = sub.add_parser("doctor", help="check blog routes and SEO output invariants")
     doctor.add_argument("project", nargs="?", default=".")
     doctor.add_argument("--require-bootstrap", action="store_true")
@@ -1121,5 +1131,7 @@ def parser() -> argparse.ArgumentParser:
 
 
 if __name__ == "__main__":
+    if sys.argv[1:2] == ["feedback"]:
+        raise SystemExit(command_feedback(argparse.Namespace(feedback_args=sys.argv[2:])))
     arguments = parser().parse_args()
     raise SystemExit(arguments.func(arguments))

package/bundled-tools/clis/maggie_analytics.py

@@ -67,6 +67,18 @@ def release_gate(args: argparse.Namespace) -> int:
             check("referral-contract", set(contract["referralSources"]).issubset({"search", "partner", "social", "email", "direct", "unknown"}), "referral categories use the redacted taxonomy", checks)
         else:
             check("referral-contract", False, "contract must declare referralSources", checks)
+        consent = contract.get("consent")
+        valid_consent = (
+            isinstance(consent, dict)
+            and consent.get("defaultBeforeContainer") is True
+            and consent.get("firstPartyStorageMode") in {"stop", "degrade"}
+            and consent.get("intentionalFormMode") in {"record", "omit"}
+        )
+        check(
+            "consent-contract", valid_consent,
+            "consent defaults precede the container and first-party/form behavior is explicit",
+            checks,
+        )
     browser, browser_errors = load_json(Path(args.render_report).resolve(), "render-report")
     errors.extend(browser_errors)
     network, network_errors = load_json(Path(args.network_report).resolve(), "network-report")
@@ -79,6 +91,28 @@ def release_gate(args: argparse.Namespace) -> int:
         check("browser-schema", browser.get("schemaVersion") == "maggie-analytics-browser.v1", "versioned browser evidence", checks)
         check("browser-render", browser.get("passed") is True and isinstance(browser.get("routes"), list) and bool(browser["routes"]), "routes rendered without a browser failure", checks)
         check("browser-console", isinstance(browser.get("consoleErrors"), list) and not browser["consoleErrors"], "no browser console errors", checks)
+        consent = contract.get("consent") if contract else None
+        browser_consent = browser.get("consent")
+        check(
+            "consent-ordering", isinstance(consent, dict) and isinstance(browser_consent, dict)
+            and browser_consent.get("defaultBeforeContainer") is True
+            and browser_consent.get("containerLoadedAfterDefault") is True,
+            "browser evidence proves default consent precedes container loading",
+            checks,
+        )
+        check(
+            "first-party-scope", isinstance(consent, dict) and isinstance(browser_consent, dict)
+            and browser_consent.get("firstPartyStorageMode") == consent.get("firstPartyStorageMode")
+            and browser_consent.get("firstPartyStorageObserved") is True,
+            "browser evidence proves the declared first-party storage behavior",
+            checks,
+        )
+        check(
+            "intentional-form-scope", isinstance(consent, dict) and isinstance(browser_consent, dict)
+            and browser_consent.get("intentionalFormMode") == consent.get("intentionalFormMode"),
+            "browser evidence records the declared intentional-form behavior",
+            checks,
+        )
     if network:
         pre = network.get("preConsentRequests")
         check("pre-consent-network", isinstance(pre, list) and not pre, "no analytics requests before consent", checks)

package/bundled-tools/clis/maggie_blog.py

@@ -12,6 +12,7 @@ sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "runtime"))
 from maggie_blog import BlogStore, review_settings_from_adapter  # noqa: E402
 from localization_runner import process_adapter
 from integration_state import integration_state  # noqa: E402
+from maggie_blog_publish import validate_auto_publish  # noqa: E402
 
 
 def main() -> int:
@@ -28,6 +29,9 @@ def main() -> int:
     ingest = sub.add_parser("ingest"); ingest.add_argument("--project", type=Path, default=Path.cwd()); ingest.add_argument("--input", type=Path, required=True); ingest.add_argument("--source", default="local"); ingest.add_argument("--confirm", action="store_true")
     validate = sub.add_parser("validate"); validate.add_argument("--project", type=Path, default=Path.cwd())
     gate = sub.add_parser("check-gate", help="report whether generated content requires review before publication"); gate.add_argument("--project", type=Path, default=Path.cwd()); gate.add_argument("--settings-file", type=Path, help="sanitized host settings JSON"); gate.add_argument("--adapter-command", help="trusted provider JSON argv array that prints sanitized settings JSON"); gate.add_argument("--timeout", type=int, default=120)
+    auto_gate = sub.add_parser("auto-publish-gate", help="validate explicit opt-in evidence before an automated publish")
+    auto_gate.add_argument("--evidence", type=Path, required=True)
+    auto_gate.add_argument("--output", type=Path, required=True)
     approve = sub.add_parser("approve"); approve.add_argument("--project", type=Path, default=Path.cwd()); approve.add_argument("--slug", required=True); approve.add_argument("--actor", required=True); approve.add_argument("--reason", required=True); approve.add_argument("--confirm", action="store_true")
     publish = sub.add_parser("publish"); publish.add_argument("--project", type=Path, default=Path.cwd()); publish.add_argument("--slug", required=True); publish.add_argument("--actor", required=True); publish.add_argument("--reason", required=True); publish.add_argument("--confirm", action="store_true")
     sitemap = sub.add_parser("sitemap"); sitemap.add_argument("--project", type=Path, default=Path.cwd())
@@ -35,6 +39,15 @@ def main() -> int:
     state = sub.add_parser("integration-state"); state.add_argument("--configured", action="store_true"); state.add_argument("--consent-required", action="store_true"); state.add_argument("--consent", action="store_true"); state.add_argument("--authorized", action="store_true"); state.add_argument("--error")
     rollback = sub.add_parser("rollback"); rollback.add_argument("--project", type=Path, default=Path.cwd()); rollback.add_argument("--backup"); rollback.add_argument("--confirm", action="store_true")
     args = parser.parse_args()
+    if args.command == "auto-publish-gate":
+        try:
+            result = validate_auto_publish(json.loads(args.evidence.resolve().read_text(encoding="utf-8")))
+            args.output.resolve().parent.mkdir(parents=True, exist_ok=True)
+            args.output.resolve().write_text(json.dumps(result, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+        except (OSError, ValueError, json.JSONDecodeError) as error:
+            print(f"maggie-blog: {error}", file=sys.stderr); return 1
+        print(json.dumps(result, indent=2, ensure_ascii=False))
+        return 0 if result["passed"] else 1
     if args.command == "integration-state":
         result = integration_state(configured=args.configured, consent_required=args.consent_required, consent=args.consent, authorized=args.authorized, error=args.error)
         print(json.dumps(result, indent=2, ensure_ascii=False))

package/bundled-tools/clis/maggie_dash.py

@@ -27,6 +27,7 @@ from maggie_sections import catalogue, remap_translations, section_id_migration,
 from maggie_quality import validate_variant_copy, validate_media_uniqueness, classify_inventory, validate_bindings, validate_reconcile_contract  # noqa: E402
 from maggie_api_contract import load_api_contract_source, validate_api_contract  # noqa: E402
 from maggie_dash_runtime import validate_runtime_evidence  # noqa: E402
+from maggie_dash_panels import validate_panel_report  # noqa: E402
 from maggie_schema_audit import audit_schema_inventory  # noqa: E402
 from route_imports import classify_bindings  # noqa: E402
 
@@ -374,6 +375,18 @@ def command_ui(args: argparse.Namespace) -> int:
     return 0 if result["passed"] else 1
 
 
+def command_panels(args: argparse.Namespace) -> int:
+    value = json.loads(Path(args.report).resolve().read_text(encoding="utf-8"))
+    result = validate_panel_report(value)
+    if args.output:
+        output = Path(args.output).resolve()
+        output.parent.mkdir(parents=True, exist_ok=True)
+        output.write_text(json.dumps(result, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+        result["output"] = str(output)
+    emit(result)
+    return 0 if result["passed"] else 1
+
+
 def command_sections(args: argparse.Namespace) -> int:
     if args.sections_command == "remap-translations":
         require_confirm(args)
@@ -711,6 +724,10 @@ def parser() -> argparse.ArgumentParser:
     conformance.add_argument("--evidence", required=True, help="sanitized endpoint observations JSON")
     conformance.add_argument("--output")
     conformance.set_defaults(func=command_conformance)
+    panels = sub.add_parser("panels-validate", help="validate dashboard panel source and freshness evidence")
+    panels.add_argument("--report", required=True, help="sanitized measurement-panel evidence JSON")
+    panels.add_argument("--output")
+    panels.set_defaults(func=command_panels)
     schema_audit = sub.add_parser("schema-audit", help="find declared tables with missing reader evidence")
     schema_audit.add_argument("--inventory", required=True, help="host-produced schema inventory JSON")
     schema_audit.add_argument("--fail-on-unread", action="store_true")

package/bundled-tools/clis/maggie_deployment.py

@@ -6,10 +6,77 @@ import argparse
 import json
 import re
 import subprocess
+import sys
 from datetime import datetime, timezone
 from pathlib import Path
 
 
+DEPLOYMENT_CREDENTIALS = (
+    "DEPLOY_SERVER_IP",
+    "DEPLOY_SERVER_SSH_USER",
+    "DEPLOY_SERVER_SSH_PASSWORD",
+    "DEPLOY_SERVER_SSH_SUDOER",
+)
+
+
+def parse_env_file(path: Path) -> dict[str, str]:
+    values: dict[str, str] = {}
+    for line in path.read_text(encoding="utf-8", errors="replace").splitlines():
+        line = line.strip()
+        if not line or line.startswith("#"):
+            continue
+        if line.startswith("export "):
+            line = line[7:].lstrip()
+        if "=" not in line:
+            continue
+        key, value = line.split("=", 1)
+        values[key.strip()] = value.strip().strip("\"'")
+    return values
+
+
+def credential_preflight(env_file: Path, expected_host: str | None = None) -> dict:
+    """Check deployment variable presence without returning secret values."""
+    errors: list[str] = []
+    try:
+        values = parse_env_file(env_file)
+    except OSError as error:
+        values = {}
+        errors.append(f"cannot read env file: {error}")
+    present = {name: bool(values.get(name, "").strip()) for name in DEPLOYMENT_CREDENTIALS}
+    if not all(present.values()):
+        errors.append("required deployment credentials are missing from the env file")
+    host_guard = {"status": "not_requested", "matches": None}
+    if expected_host:
+        host_guard = {"status": "passed" if values.get("DEPLOY_SERVER_IP") == expected_host else "failed", "matches": values.get("DEPLOY_SERVER_IP") == expected_host}
+        if host_guard["status"] == "failed":
+            errors.append("DEPLOY_SERVER_IP does not match --expected-host")
+    return {
+        "schemaVersion": "maggie-deployment-credentials.v1",
+        "envFileProvided": True,
+        "credentialSource": "project-env-file",
+        "variables": present,
+        "hostGuard": host_guard,
+        "passed": not errors,
+        "errors": errors,
+        "mutation": "not executed",
+    }
+
+
+def credential_preflight_main(argv: list[str]) -> int:
+    parser = argparse.ArgumentParser(description="Check named deployment credentials without printing their values.")
+    parser.add_argument("--env-file", required=True)
+    parser.add_argument("--expected-host")
+    parser.add_argument("--output")
+    args = parser.parse_args(argv)
+    result = credential_preflight(Path(args.env_file).expanduser().resolve(), args.expected_host)
+    if args.output:
+        output = Path(args.output).resolve()
+        output.parent.mkdir(parents=True, exist_ok=True)
+        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 result["passed"] else 1
+
+
 def preflight(project: Path, target: str, environment: str) -> dict:
     package_path = project / "package.json"
     package = json.loads(package_path.read_text(encoding="utf-8")) if package_path.exists() else {}
@@ -78,23 +145,37 @@ def preflight(project: Path, target: str, environment: str) -> dict:
     return result
 
 
-def vps_plan(domain: str, service: str, release_root: str, node_port: int | None) -> dict:
+def vps_plan(domain: str, service: str, release_root: str, node_port: int | None, deployer_user: str = "maggie-deploy") -> dict:
     """Create reviewable, secret-free VPS service and reverse-proxy artifacts."""
     if not re.fullmatch(r"[A-Za-z0-9](?:[A-Za-z0-9.-]*[A-Za-z0-9])?", domain):
         raise ValueError("domain must be a hostname without a scheme or path")
     if not re.fullmatch(r"[A-Za-z0-9_.@-]+", service):
         raise ValueError("service must contain only safe systemd name characters")
+    if not re.fullmatch(r"[a-z_][a-z0-9_-]{0,31}\$?", deployer_user):
+        raise ValueError("deployer user must be a safe local account name")
     if node_port is None:
         raise ValueError("node port must be supplied explicitly; choose an unused port for this host")
     if not 1024 <= node_port <= 65535:
         raise ValueError("node port must be between 1024 and 65535")
     root = release_root.rstrip("/")
     current = f"{root}/current"
+    privileged_commands = [
+        f"/bin/systemctl restart {service}",
+        f"/bin/systemctl is-active {service}",
+    ]
     return {
         "schema_version": "1.0",
         "provider": "vps-with-cloudflare-dns",
         "domain": domain,
         "service": service,
+        "deployer_user": deployer_user,
+        "application_user": "www-data",
+        "privileged_commands": privileged_commands,
+        "sudoers": {
+            "user": deployer_user,
+            "commands": privileged_commands,
+            "policy": "exact service commands only; no shell, wildcard, or broad sudo",
+        },
         "release_root": root,
         "current_release": current,
         "node_port": node_port,
@@ -111,9 +192,9 @@ def vps_plan(domain: str, service: str, release_root: str, node_port: int | None
         "commands": {
             "stage": "npm ci && npm run typecheck && npm run build",
             "switch": f"ln -sfn {root}/releases/<release> {current}",
-            "restart": f"systemctl restart {service}",
-            "verify": f"systemctl is-active {service} && curl -fsS https://{domain}/robots.txt && curl -fsS https://{domain}/sitemap.xml",
-            "rollback": f"ln -sfn {root}/releases/<previous-release> {current} && systemctl restart {service}",
+            "restart": f"sudo -n /bin/systemctl restart {service}",
+            "verify": f"sudo -n /bin/systemctl is-active {service} && curl -fsS https://{domain}/robots.txt && curl -fsS https://{domain}/sitemap.xml",
+            "rollback": f"ln -sfn {root}/releases/<previous-release> {current} && sudo -n /bin/systemctl restart {service}",
             "data_rollback": "restore the matching data checkpoint before restarting the previous code release",
         },
         "files": {
@@ -285,8 +366,8 @@ if [ -d "$CURRENT/.agents" ]; then cp -a "$CURRENT/.agents" "$RELEASE/.agents";
 if [ -d "$CURRENT/.claude" ]; then cp -a "$CURRENT/.claude" "$RELEASE/.claude"; fi
 
 ln -sfn "$RELEASE" "$CURRENT"
-systemctl restart "{service}"
-systemctl is-active --quiet "{service}"
+sudo -n /bin/systemctl restart "{service}"
+sudo -n /bin/systemctl is-active --quiet "{service}"
 curl -fsS "https://{domain}/robots.txt" >/dev/null
 curl -fsS "https://{domain}/sitemap.xml" >/dev/null
 
@@ -307,6 +388,8 @@ def write_release_runner(path: Path, plan: dict) -> None:
 
 
 def main() -> int:
+    if sys.argv[1:2] == ["credential-preflight"]:
+        return credential_preflight_main(sys.argv[2:])
     parser = argparse.ArgumentParser(description=__doc__)
     parser.add_argument("project", nargs="?", default=".")
     parser.add_argument("--target", choices=("detected", "cloudflare", "vps", "vps-with-cloudflare-dns", "gcp", "aws"), default="detected")
@@ -317,6 +400,7 @@ def main() -> int:
     parser.add_argument("--service", default="maggie-site", help="systemd service name")
     parser.add_argument("--release-root", default="/var/www/maggie-site", help="immutable release root")
     parser.add_argument("--node-port", type=int, required=False, default=None, help="unused host port; required with --vps-plan")
+    parser.add_argument("--deployer-user", default="maggie-deploy", help="dedicated least-privilege SSH/deploy account")
     parser.add_argument("--plan-dir", help="directory for generated VPS artifacts")
     parser.add_argument("--runner-output", help="write a reviewable ordered VPS release runner")
     parser.add_argument("--retention-plan", action="store_true", help="create a read-only release prune candidate plan")
@@ -334,7 +418,7 @@ def main() -> int:
         if args.vps_plan:
             if not args.domain:
                 parser.error("--domain is required with --vps-plan")
-            plan = vps_plan(args.domain, args.service, args.release_root, args.node_port)
+            plan = vps_plan(args.domain, args.service, args.release_root, args.node_port, args.deployer_user)
             if args.plan_dir:
                 write_vps_plan(Path(args.plan_dir).resolve(), plan)
             if args.runner_output:

package/bundled-tools/clis/maggie_feedback.py

@@ -151,10 +151,20 @@ def collect(args: argparse.Namespace) -> int:
     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")
+        batch_base = getattr(args, "batch_base", 0)
+        if batch_base not in (0, 1):
+            raise ValueError("batch base must be 0 or 1")
+        if not isinstance(batch_index, int) or isinstance(batch_index, bool):
+            raise ValueError(f"batch index is required and must be {batch_base}-based when batch ID is provided")
+        if not isinstance(batch_size, int) or isinstance(batch_size, bool) or batch_size < 1:
+            raise ValueError("batch size must be a positive integer")
+        if batch_base == 1 and not 1 <= batch_index <= batch_size:
+            raise ValueError(f"1-based batch index must be between 1 and {batch_size} inclusive")
+        if batch_base == 0 and not 0 <= batch_index < batch_size:
+            raise ValueError(f"0-based batch index must be between 0 and {batch_size - 1} inclusive; use --batch-base 1 for 1-based input")
+        # Persist one canonical representation so batch review and the hosted
+        # API do not have to guess which indexing convention was used.
+        batch_index -= batch_base
     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")
@@ -428,6 +438,10 @@ def main() -> int:
     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(
+        "--batch-base", type=int, choices=(0, 1), default=0,
+        help="indexing convention for --batch-index (default: 0; use 1 for 1-based input)",
+    )
     collect_parser.add_argument("--priority", choices=("low", "normal", "high", "critical"), default="normal")
     collect_parser.add_argument("--affected-cli", default="")
     collect_parser.add_argument("--route-id", dest="route_ids", action="append", default=[])

package/bundled-tools/clis/maggie_icon_release_gate.py

@@ -0,0 +1,79 @@
+#!/usr/bin/env python3
+"""Validate the complete source-to-browser icon release gate."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+from typing import Any
+
+
+def validate(icon_report: object, browser_report: object) -> dict[str, Any]:
+    errors: list[str] = []
+    if not isinstance(icon_report, dict):
+        errors.append("icon report must be an object")
+        icon_report = {}
+    if not isinstance(browser_report, dict):
+        errors.append("browser report must be an object")
+        browser_report = {}
+    source_ok = (
+        icon_report.get("schemaVersion") == "maggie-icon-inventory.v1"
+        and icon_report.get("status") == "pass"
+        and icon_report.get("missing") == []
+        and icon_report.get("unknown") == []
+    )
+    if not source_ok:
+        errors.append("source/runtime icon inventory did not pass")
+    browser_ok = browser_report.get("schemaVersion") == "maggie-icon-browser-evidence.v1" and browser_report.get("passed") is True and isinstance(browser_report.get("routes"), list) and bool(browser_report["routes"])
+    if not browser_ok:
+        errors.append("browser icon evidence did not pass")
+    icons = browser_report.get("icons") if isinstance(browser_report.get("icons"), list) else []
+    if not icons:
+        errors.append("browser evidence must include painted icons")
+    invalid: list[str] = []
+    for index, icon in enumerate(icons):
+        name = str(icon.get("name") or f"icon-{index}") if isinstance(icon, dict) else f"icon-{index}"
+        if not isinstance(icon, dict) or icon.get("visible") is not True or not isinstance(icon.get("width"), (int, float)) or icon["width"] <= 0 or not isinstance(icon.get("height"), (int, float)) or icon["height"] <= 0 or not str(icon.get("accessibleName") or "").strip():
+            invalid.append(name)
+        if not isinstance(icon, dict) or not isinstance(icon.get("assetStatus"), int) or not 200 <= icon["assetStatus"] <= 299:
+            invalid.append(name)
+    if invalid:
+        errors.append("browser icon evidence has invisible, zero-size, inaccessible, or unserved glyphs")
+    return {
+        "schemaVersion": "maggie-icon-release-gate.v1",
+        "passed": not errors,
+        "errors": sorted(set(errors)),
+        "checks": {
+            "sourceRuntime": source_ok,
+            "servedAssets": browser_ok and not bool(invalid),
+            "paintedGlyphs": bool(icons) and not bool(invalid),
+            "accessibility": bool(icons) and not bool(invalid),
+        },
+        "iconCount": len(icons),
+        "invalidIcons": sorted(set(invalid)),
+        "mutation": "not executed",
+    }
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--icon-report", required=True)
+    parser.add_argument("--browser-report", required=True)
+    parser.add_argument("--output", required=True)
+    args = parser.parse_args()
+    try:
+        icon = json.loads(Path(args.icon_report).resolve().read_text(encoding="utf-8"))
+        browser = json.loads(Path(args.browser_report).resolve().read_text(encoding="utf-8"))
+        result = validate(icon, browser)
+        output = Path(args.output).resolve()
+        output.parent.mkdir(parents=True, exist_ok=True)
+        output.write_text(json.dumps(result, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+    except (OSError, json.JSONDecodeError) as error:
+        result = {"schemaVersion": "maggie-icon-release-gate.v1", "passed": False, "errors": [f"cannot read icon evidence: {error}"], "mutation": "not executed"}
+    print(json.dumps(result, indent=2, ensure_ascii=False))
+    return 0 if result["passed"] else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/bundled-tools/clis/maggie_migration.py

@@ -58,6 +58,8 @@ def validate_project(project: Path, environment: str) -> dict:
 IDENTITY_SCHEMA = "maggie-database-identity.v1"
 PREFLIGHT_SCHEMA = "maggie-migration-preflight.v1"
 SAFE_NAME = re.compile(r"^[A-Za-z][A-Za-z0-9_.:-]{0,119}$")
+LEDGER_SCHEMA = "maggie-migration-ledger.v1"
+MIGRATION_FILE = re.compile(r"^(\d{1,9})[_-][A-Za-z0-9][A-Za-z0-9_.-]*\.sql$")
 
 
 def _identity_fingerprint(identity: dict) -> str:
@@ -160,11 +162,80 @@ def preflight_main(argv: list[str]) -> int:
     print(json.dumps(result, indent=2)); return 0 if not errors else 1
 
 
+def reconcile_main(argv: list[str]) -> int:
+    """Compare host-reported applied migrations with local migration files."""
+    parser = argparse.ArgumentParser(description="Build a read-only ordered plan for migrations missing from the server ledger.")
+    parser.add_argument("--evidence", required=True, help="host-produced ledger evidence JSON")
+    parser.add_argument("--migration-dir", required=True, help="directory containing numbered .sql migrations")
+    parser.add_argument("--output")
+    args = parser.parse_args(argv)
+    errors: list[str] = []
+    try:
+        evidence = json.loads(Path(args.evidence).read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as error:
+        evidence = {}
+        errors.append(f"cannot read migration ledger evidence: {error}")
+    if not isinstance(evidence, dict):
+        evidence = {}
+        errors.append("migration ledger evidence must be an object")
+    if evidence.get("schemaVersion") != LEDGER_SCHEMA:
+        errors.append(f"schemaVersion must be {LEDGER_SCHEMA}")
+    if evidence.get("migrationTable") != "maggie_schema_migrations":
+        errors.append("migrationTable must be maggie_schema_migrations")
+    if evidence.get("environment") not in {"development", "staging", "production"}:
+        errors.append("environment is invalid")
+    applied = evidence.get("appliedVersions")
+    if not isinstance(applied, list) or any(not re.fullmatch(r"\d{1,9}", str(item)) for item in applied) or len(set(map(str, applied))) != len(applied):
+        errors.append("appliedVersions must be a unique array of numeric versions")
+        applied = []
+    applied_set = {str(item).zfill(3) for item in applied}
+    files: list[tuple[str, str]] = []
+    migration_dir = Path(args.migration_dir).resolve()
+    try:
+        entries = sorted(migration_dir.iterdir())
+    except OSError as error:
+        entries = []
+        errors.append(f"cannot read migration directory: {error}")
+    for entry in entries:
+        if not entry.is_file():
+            continue
+        match = MIGRATION_FILE.fullmatch(entry.name)
+        if match:
+            files.append((match.group(1).zfill(3), entry.name))
+    if not files:
+        errors.append("migration directory contains no numbered .sql files")
+    versions = [version for version, _ in files]
+    if len(set(versions)) != len(versions):
+        errors.append("migration directory contains duplicate migration versions")
+    ordered = [{"version": version, "file": name, "applied": version in applied_set} for version, name in sorted(files)]
+    missing = [item for item in ordered if not item["applied"]]
+    result = {
+        "schemaVersion": "maggie-migration-ledger-result.v1",
+        "environment": evidence.get("environment"),
+        "migrationTable": evidence.get("migrationTable"),
+        "passed": not errors and not missing,
+        "errors": errors,
+        "appliedVersions": sorted(applied_set),
+        "orderedMigrations": ordered,
+        "missing": missing,
+        "nextAction": "activate only after applying missing migrations in order" if missing else "ledger matches migration directory",
+        "mutation": "not executed",
+    }
+    if args.output:
+        output = Path(args.output)
+        output.parent.mkdir(parents=True, exist_ok=True)
+        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 result["passed"] else 1
+
+
 def main() -> int:
     if sys.argv[1:2] == ["preflight"]:
         return preflight_main(sys.argv[2:])
     if sys.argv[1:2] == ["identity"]:
         return identity_main(sys.argv[2:])
+    if sys.argv[1:2] == ["reconcile"]:
+        return reconcile_main(sys.argv[2:])
     parser = argparse.ArgumentParser(description=__doc__)
     parser.add_argument("manifest", nargs="?")
     parser.add_argument("--project")