@topy-ai/maggie 0.7.45 → 0.7.47

package/bundled-tools/clis/maggie_feedback.py

@@ -30,8 +30,15 @@ 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}$")
 SAFE_ROUTE_RE = re.compile(r"^/[A-Za-z0-9._~!$&'()*+,;=:@%/?#-]{1,240}$")
 SAFE_EVIDENCE_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._:/=-]{0,159}$")
+SAFE_FEEDBACK_ID_RE = re.compile(r"^fb-[A-Za-z0-9_-]{1,159}$")
 MAX_ROUTE_IDS = 20
 MAX_VALIDATION_EVIDENCE = 20
+MAX_EVIDENCE_REFERENCES = 20
+MAX_RELATIONSHIPS = 20
+MAX_GRAPH_NODES = 200
+MAX_GRAPH_EDGES = 300
+EVIDENCE_KINDS = {"test", "report", "screenshot", "command", "deployment", "issue", "commit", "artifact"}
+RELATION_KINDS = {"related", "same-run", "same-fingerprint", "duplicates", "validates", "remediates", "caused-by"}
 ACKNOWLEDGEMENT_KEYS = ("status", "feedbackId", "requestId")
 REPO_ROOT = Path(__file__).resolve().parents[2]
 
@@ -134,6 +141,64 @@ def safe_validation_evidence(values: object) -> list[str]:
     return sorted(set(result))
 
 
+def safe_evidence_references(values: object) -> list[dict]:
+    """Normalize bounded evidence pointers without copying artifacts or payloads."""
+    if not isinstance(values, list):
+        return []
+    result = []
+    for value in values[:MAX_EVIDENCE_REFERENCES]:
+        if isinstance(value, str):
+            if ":" not in value:
+                continue
+            kind, reference = value.split(":", 1)
+            status = "observed"
+        elif isinstance(value, dict):
+            kind = value.get("kind", "")
+            reference = value.get("ref", "")
+            status = value.get("status", "observed")
+        else:
+            continue
+        kind = safe_text(kind).lower()
+        reference = safe_text(reference)
+        status = safe_text(status).lower()
+        if kind not in EVIDENCE_KINDS or not SAFE_EVIDENCE_RE.fullmatch(reference):
+            continue
+        if status not in {"passed", "failed", "observed", "not-run", "unknown"}:
+            status = "unknown"
+        result.append({"kind": kind, "ref": reference, "status": status})
+    return sorted({(item["kind"], item["ref"], item["status"]): item for item in result}.values(),
+                  key=lambda item: (item["kind"], item["ref"], item["status"]))
+
+
+def safe_relationships(values: object) -> list[dict]:
+    """Normalize links to other safe IDs; never accept URLs or arbitrary payloads."""
+    if not isinstance(values, list):
+        return []
+    result = []
+    for value in values[:MAX_RELATIONSHIPS]:
+        if isinstance(value, str):
+            if "=" not in value:
+                continue
+            kind, target = value.split("=", 1)
+            confidence = "medium"
+        elif isinstance(value, dict):
+            kind = value.get("kind", "")
+            target = value.get("target", "")
+            confidence = value.get("confidence", "medium")
+        else:
+            continue
+        kind = safe_text(kind).lower()
+        target = safe_text(target)
+        confidence = safe_text(confidence).lower()
+        if kind not in RELATION_KINDS or not SAFE_EVIDENCE_RE.fullmatch(target):
+            continue
+        if confidence not in {"low", "medium", "high"}:
+            confidence = "medium"
+        result.append({"kind": kind, "target": target, "confidence": confidence})
+    return sorted({(item["kind"], item["target"], item["confidence"]): item for item in result}.values(),
+                  key=lambda item: (item["kind"], item["target"], item["confidence"]))
+
+
 def collect(args: argparse.Namespace) -> int:
     project = Path(args.project).resolve()
     report = load_json(Path(args.run_report)) if args.run_report else {}
@@ -171,6 +236,8 @@ def collect(args: argparse.Namespace) -> int:
     affected_cli = safe_text(getattr(args, "affected_cli", ""))
     route_ids = safe_route_ids(getattr(args, "route_ids", []))
     validation_evidence = safe_validation_evidence(getattr(args, "validation_evidence", []))
+    evidence = safe_evidence_references(getattr(args, "evidence", []))
+    relationships = safe_relationships(getattr(args, "relationships", []))
     context = {"projectFingerprint": project_fingerprint(project)}
     if args.allow_project_context and args.context_note:
         context["note"] = safe_text(args.context_note)
@@ -197,6 +264,8 @@ def collect(args: argparse.Namespace) -> int:
         "affectedCli": affected_cli,
         "routeIds": route_ids,
         "validationEvidence": validation_evidence,
+        "evidence": evidence,
+        "relationships": relationships,
         "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)},
@@ -226,7 +295,7 @@ def to_markdown(data: dict) -> str:
     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)", ""]
+    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'}", f"**Evidence references:** `{len(safe_evidence_references(data.get('evidence', [])))}`", f"**Relationships:** `{len(safe_relationships(data.get('relationships', [])))}`", "", "## Privacy", "", f"- Project context allowed: `{bool(data.get('privacy', {}).get('projectContextAllowed'))}`", f"- Attachments: `{len(data.get('attachments', []))}` metadata-only reference(s)", ""]
     return "\n".join(lines)
 
 
@@ -307,6 +376,8 @@ def collect_batch(args: argparse.Namespace) -> int:
         "affected_cli": safe_text(manifest.get("affectedCli")),
         "route_ids": safe_route_ids(manifest.get("routeIds", [])),
         "validation_evidence": safe_validation_evidence(manifest.get("validationEvidence", [])),
+        "evidence": safe_evidence_references(manifest.get("evidence", [])),
+        "relationships": safe_relationships(manifest.get("relationships", [])),
     }
     paths = []
     for index, item in enumerate(items):
@@ -337,11 +408,15 @@ def collect_batch(args: argparse.Namespace) -> int:
             "affected_cli": item.get("affectedCli") or shared["affected_cli"],
             "route_ids": item.get("routeIds", shared["route_ids"]),
             "validation_evidence": item.get("validationEvidence", shared["validation_evidence"]),
+            "evidence": item.get("evidence", shared["evidence"]),
+            "relationships": item.get("relationships", shared["relationships"]),
         }
         if not isinstance(values["reproduce"], list): values["reproduce"] = []
         if not isinstance(values["screenshot"], list): values["screenshot"] = []
         values["route_ids"] = safe_route_ids(values["route_ids"])
         values["validation_evidence"] = safe_validation_evidence(values["validation_evidence"])
+        values["evidence"] = safe_evidence_references(values["evidence"])
+        values["relationships"] = safe_relationships(values["relationships"])
         paths.append(collect(argparse.Namespace(**values)))
     print(json.dumps({"batchId": batch_id, "count": len(paths), "status": "drafts-created"}, ensure_ascii=False))
     return 0
@@ -380,6 +455,8 @@ def batch_review(args: argparse.Namespace) -> int:
             "validation": safe_text(data.get("validation")),
             "routeIds": safe_route_ids(data.get("routeIds", [])),
             "validationEvidence": safe_validation_evidence(data.get("validationEvidence", [])),
+            "evidence": safe_evidence_references(data.get("evidence", [])),
+            "relationships": safe_relationships(data.get("relationships", [])),
         })
     records.sort(key=lambda item: (item["index"] is None, item["index"] if isinstance(item["index"], int) else 0, item["feedbackId"]))
     expected_count = max(expected_sizes, default=len(records))
@@ -390,6 +467,39 @@ def batch_review(args: argparse.Namespace) -> int:
         if key:
             duplicate_groups.setdefault(key, []).append(item["feedbackId"])
     duplicates = [{"key": safe_text(key), "feedbackIds": ids} for key, ids in duplicate_groups.items() if len(ids) > 1]
+    graph_nodes = [{"id": item["feedbackId"], "kind": "feedback"} for item in records]
+    graph_edges = []
+    evidence_nodes = {}
+    for item in records:
+        for evidence in item["evidence"]:
+            evidence_key = f"{evidence['kind']}:{evidence['ref']}"
+            evidence_id = "evidence-" + hashlib.sha256(evidence_key.encode("utf-8")).hexdigest()[:16]
+            evidence_nodes.setdefault(evidence_id, {"id": evidence_id, "kind": "evidence", **evidence})
+            graph_edges.append({"from": item["feedbackId"], "to": evidence_id, "kind": "evidenced-by"})
+        for relationship in item["relationships"]:
+            target = relationship["target"]
+            target_id = target if SAFE_FEEDBACK_ID_RE.fullmatch(target) else "reference-" + hashlib.sha256(target.encode("utf-8")).hexdigest()[:16]
+            if not any(node["id"] == target_id for node in graph_nodes):
+                graph_nodes.append({"id": target_id, "kind": "related-reference"})
+            graph_edges.append({"from": item["feedbackId"], "to": target_id, "kind": relationship["kind"], "confidence": relationship["confidence"]})
+    graph_nodes.extend(evidence_nodes.values())
+    graph_nodes = graph_nodes[:MAX_GRAPH_NODES]
+    allowed_node_ids = {node["id"] for node in graph_nodes}
+    graph_edges = [edge for edge in graph_edges if edge["from"] in allowed_node_ids and edge["to"] in allowed_node_ids][:MAX_GRAPH_EDGES]
+    evidence_usage = {}
+    for item in records:
+        for evidence in item["evidence"]:
+            key = f"{evidence['kind']}:{evidence['ref']}"
+            evidence_usage.setdefault(key, []).append(item["feedbackId"])
+    remediation_suggestions = []
+    if duplicates:
+        remediation_suggestions.append("Review duplicate fingerprints or summaries and link one canonical remediation issue before implementation.")
+    if len(records) != expected_count:
+        remediation_suggestions.append("Collect the missing batch indexes before treating this batch as complete.")
+    if any(len(ids) > 1 for ids in evidence_usage.values()):
+        remediation_suggestions.append("Inspect shared evidence references for a common root cause and reuse one regression test where appropriate.")
+    if not any(item["evidence"] for item in records):
+        remediation_suggestions.append("Attach bounded test, report, screenshot, command, or deployment references before release review.")
     output = Path(args.output) if args.output else project / ".maggie" / "feedback" / "batches" / f"{batch_id}-review.json"
     if not output.is_absolute(): output = project / output
     report = {
@@ -403,6 +513,8 @@ def batch_review(args: argparse.Namespace) -> int:
         "phases": sorted({item["phase"] for item in records if item["phase"]}),
         "observations": records,
         "duplicates": duplicates,
+        "evidenceGraph": {"nodes": graph_nodes, "edges": graph_edges},
+        "remediationSuggestions": remediation_suggestions,
         "privacy": {"rawPayloadsIncluded": False, "localPathsIncluded": False, "secretsRedacted": True},
     }
     output.parent.mkdir(parents=True, exist_ok=True)
@@ -446,6 +558,8 @@ def main() -> int:
     collect_parser.add_argument("--affected-cli", default="")
     collect_parser.add_argument("--route-id", dest="route_ids", action="append", default=[])
     collect_parser.add_argument("--validation-evidence", dest="validation_evidence", action="append", default=[])
+    collect_parser.add_argument("--evidence-ref", dest="evidence", action="append", default=[], help="safe kind:reference pointer; no file contents are copied")
+    collect_parser.add_argument("--relationship", dest="relationships", action="append", default=[], help="safe relation=target pointer")
     batch_parser = sub.add_parser("batch")
     batch_parser.add_argument("--project", default=argparse.SUPPRESS)
     batch_parser.add_argument("--batch-file", required=True)
@@ -461,6 +575,7 @@ def main() -> int:
     submit_parser.add_argument("--endpoint", default=DEFAULT_ENDPOINT)
     submit_parser.add_argument("--confirm", action="store_true")
     list_parser = sub.add_parser("list")
+    list_parser.add_argument("--project", default=argparse.SUPPRESS)
     args = parser.parse_args()
     try:
         if args.command == "collect": return collect(args)

package/bundled-tools/clis/maggie_memory.py

@@ -35,12 +35,15 @@ def main() -> int:
     listing.add_argument("--status", choices=sorted(memory.STATUSES), default=None)
     listing.add_argument("--skill", default="")
     listing.add_argument("--query", default="")
+    listing.add_argument("--include-shared", action="store_true", help="explicitly include user/workspace memory entries")
     search = add_project(sub.add_parser("search"))
     search.add_argument("query")
     search.add_argument("--skill", default="")
+    search.add_argument("--include-shared", action="store_true", help="explicitly include user/workspace memory entries")
     context = add_project(sub.add_parser("context"))
     context.add_argument("--skill", default="")
     context.add_argument("--query", default="")
+    context.add_argument("--include-shared", action="store_true", help="explicitly include user/workspace memory entries")
     add = add_project(sub.add_parser("add"))
     add.add_argument("kind", choices=("preferences", "conventions", "lessons"))
     add.add_argument("--scope", choices=sorted(memory.SCOPES), required=True)
@@ -85,17 +88,21 @@ def main() -> int:
             output(memory.transition(args.project, args.kind, args.item_id, args.status))
         elif args.command in {"context", "search", "list"}:
             query = args.query if args.command == "search" else getattr(args, "query", "")
-            result = memory.relevant(args.project, skill=getattr(args, "skill", ""), query=query, status=getattr(args, "status", None))
+            result = memory.relevant(args.project, skill=getattr(args, "skill", ""), query=query, status=getattr(args, "status", None), include_shared=getattr(args, "include_shared", False))
             if args.command == "list" and args.kind:
                 result = {args.kind: result[args.kind]}
             if args.command == "list" and args.status:
                 result = {kind: [item for item in items if item.get("status") == args.status] for kind, items in result.items()}
-            output(result)
+            if args.command == "context":
+                ready = memory.initialized(args.project)
+                output({"status": "ready" if ready else "uninitialized", "initialized": ready, **result})
+            else:
+                output(result)
         elif args.command == "export":
             payload = {kind: memory.read(args.project, kind) for kind in memory.KINDS if kind != "errors"}
             if args.public_safe:
                 for value in payload.values():
-                    value["items"] = [item for item in value["items"] if item.get("scope") != "user" and item.get("status") == "active"]
+                    value["items"] = [item for item in value["items"] if item.get("scope") == "project" and item.get("status") == "active"]
             destination = Path(args.output)
             destination.parent.mkdir(parents=True, exist_ok=True)
             destination.write_text(json.dumps(payload, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")

package/bundled-tools/clis/maggie_ops.py

@@ -16,6 +16,7 @@ from agent_runtime import preflight as agent_preflight
 from restart_gate import validate as validate_restart_gate
 from google_capabilities import validate_report as validate_google_capability_report
 from maggie_favicon import check_favicon
+from external_write import validate as validate_external_write
 
 
 REQUIRED_ROUTES = (
@@ -176,12 +177,40 @@ def command_google_capabilities(args: argparse.Namespace) -> int:
         "status": "passed" if result["passed"] else "failed",
         "report": str(output),
         "providerCount": len(result["providerResults"]),
+        "verifiedTargets": [
+            {
+                "provider": item["provider"],
+                "activeAccount": item["activeAccount"],
+                "target": item["target"],
+                "scopes": item["scopes"],
+            }
+            for item in result["providerResults"]
+        ],
         "failedChecks": result["errors"],
         "mutationsAllowed": False,
     }, indent=2, ensure_ascii=False))
     return 0 if result["passed"] else 1
 
 
+def command_external_write_gate(args: argparse.Namespace) -> int:
+    evidence = read_json(Path(args.evidence).resolve())
+    result = validate_external_write(evidence)
+    output = Path(args.output).resolve() if args.output else root(args) / ".maggie" / "external-write-readback.json"
+    write_json(output, result)
+    print(json.dumps({
+        "status": "passed" if result["passed"] else "failed",
+        "report": str(output),
+        "provider": result.get("provider"),
+        "resource": result.get("resource"),
+        "operation": result.get("operation"),
+        "idempotencyKey": result.get("idempotencyKey"),
+        "readback": result.get("readback"),
+        "failedChecks": result["errors"],
+        "mutation": "not executed",
+    }, indent=2, ensure_ascii=False))
+    return 0 if result["passed"] else 1
+
+
 def command_favicon_check(args: argparse.Namespace) -> int:
     result = check_favicon(args.origin, args.declared_url, args.timeout)
     print(json.dumps(result, indent=2, ensure_ascii=False))
@@ -210,6 +239,10 @@ def main() -> int:
     google.add_argument("--report", required=True)
     google.add_argument("--output")
     google.set_defaults(func=command_google_capabilities)
+    external_write = sub.add_parser("external-write-gate", help="validate idempotent provider write/readback evidence")
+    external_write.add_argument("--evidence", required=True)
+    external_write.add_argument("--output")
+    external_write.set_defaults(func=command_external_write_gate)
     favicon = sub.add_parser("favicon-check", help="fetch /favicon.ico and the declared icon to verify behaviour")
     favicon.add_argument("--origin", required=True)
     favicon.add_argument("--declared-url")

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