@topy-ai/maggie 0.7.38 → 0.7.41

package/bundled-tools/clis/maggie_contracts.py

@@ -0,0 +1,393 @@
+#!/usr/bin/env python3
+"""Small, deterministic validators for the cross-skill design/SEO contracts.
+
+The commands consume sanitized evidence produced by a browser/build adapter. They
+never fetch a third-party site and never write host source files implicitly.
+"""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import html as html_lib
+import json
+import re
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+from urllib.parse import urlparse
+
+
+def now() -> str:
+    return datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
+
+
+def read_json(path: Path) -> dict:
+    value = json.loads(path.read_text(encoding="utf-8"))
+    if not isinstance(value, dict):
+        raise ValueError(f"{path} must contain a JSON object")
+    return value
+
+
+def write_json(path: Path | None, value: dict) -> None:
+    if path:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(json.dumps(value, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+
+
+def result(schema: str, errors: list[str], **details: object) -> dict:
+    return {"schemaVersion": schema, "passed": not errors, "errors": errors, **details}
+
+
+def emit_and_exit(value: dict, output: Path | None = None) -> int:
+    write_json(output, value)
+    print(json.dumps(value, indent=2, ensure_ascii=False))
+    return 0 if value.get("passed") else 1
+
+
+def require_confirm(args: argparse.Namespace) -> None:
+    if not args.confirm:
+        raise ValueError("CONFIRMATION_REQUIRED: rerun with --confirm")
+
+
+def slug(value: str) -> str:
+    return re.sub(r"[^a-z0-9]+", "-", value.lower()).strip("-") or "contract"
+
+
+def init_plan(args: argparse.Namespace, mode: str, defaults: dict) -> int:
+    require_confirm(args)
+    project = Path(args.project).resolve()
+    seed = f"{project}:{mode}:{getattr(args, 'route', '')}:{now()}".encode()
+    ident = f"{mode}-{hashlib.sha256(seed).hexdigest()[:12]}"
+    output = project / ".maggie" / "design" / mode / ident / "plan.json"
+    plan = {"schemaVersion": f"maggie-{mode}-surface.v1", "id": ident, "mode": mode, "createdAt": now(), **defaults}
+    output.parent.mkdir(parents=True, exist_ok=True)
+    output.write_text(json.dumps(plan, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+    print(json.dumps({"plan": str(output), "id": ident, "mode": mode}, indent=2))
+    return 0
+
+
+def validate_progressive(args: argparse.Namespace) -> int:
+    evidence = read_json(Path(args.evidence))
+    errors: list[str] = []
+    if evidence.get("schemaVersion") != "maggie-progressive-enhancement.v1":
+        errors.append("evidence schemaVersion must be maggie-progressive-enhancement.v1")
+    region = evidence.get("region") if isinstance(evidence.get("region"), dict) else {}
+    if not region.get("id") or not region.get("selector"):
+        errors.append("region id and selector are required")
+    if region.get("swapScope") != "smallest-changed-region":
+        errors.append("swapScope must be smallest-changed-region")
+    initial = evidence.get("initial") if isinstance(evidence.get("initial"), dict) else {}
+    initial_requests = set(initial.get("thirdPartyRequests") or [])
+    initial_ids = initial.get("identities") if isinstance(initial.get("identities"), dict) else {}
+    states = evidence.get("states")
+    if not isinstance(states, list) or not states:
+        errors.append("states must be a non-empty array")
+        states = []
+    for state in states:
+        if not isinstance(state, dict):
+            errors.append("each state must be an object")
+            continue
+        new_requests = sorted(set(state.get("thirdPartyRequests") or []) - initial_requests)
+        if new_requests:
+            errors.append(f"state {state.get('name', 'unknown')} introduced third-party requests: {', '.join(new_requests)}")
+        identities = state.get("identities") if isinstance(state.get("identities"), dict) else {}
+        for identity, token in initial_ids.items():
+            if identities.get(identity) != token:
+                errors.append(f"state {state.get('name', 'unknown')} changed identity {identity}")
+        if state.get("outsideRegionStable") is not True:
+            errors.append(f"state {state.get('name', 'unknown')} lacks outsideRegionStable=true")
+    return emit_and_exit(result("maggie-progressive-enhancement.v1", errors, checkedStates=len(states), region=region), Path(args.output) if args.output else None)
+
+
+def css_escape(token: str) -> str:
+    return "".join((f"\\{char}" if char in r":[]()./%#" else char) for char in token)
+
+
+def validate_css(args: argparse.Namespace) -> int:
+    errors: list[str] = []
+    missing: list[str] = []
+    classes: list[str] = []
+    if args.evidence:
+        evidence = read_json(Path(args.evidence))
+        if evidence.get("schemaVersion") != "maggie-css-utility-evidence.v1":
+            errors.append("evidence schemaVersion must be maggie-css-utility-evidence.v1")
+        for element in evidence.get("elements") or []:
+            if not isinstance(element, dict):
+                errors.append("each CSS evidence element must be an object")
+                continue
+            for declaration in element.get("declarations") or []:
+                winner = declaration.get("winningSource") if isinstance(declaration.get("winningSource"), dict) else {}
+                if winner.get("layer") == "unlayered" or winner.get("projectRule") is True:
+                    errors.append(f"utility declaration {declaration.get('property', 'unknown')} is won by unlayered project CSS")
+    else:
+        source_html = Path(args.html).read_text(encoding="utf-8")
+        source_css = Path(args.css).read_text(encoding="utf-8")
+        for raw in re.findall(r'class=["\']([^"\']+)', source_html, re.I):
+            classes.extend(item for item in html_lib.unescape(raw).split() if ":" in item or "[" in item)
+        classes.extend(args.required_class or [])
+        for token in dict.fromkeys(classes):
+            if token not in source_css and css_escape(token) not in source_css:
+                missing.append(token)
+        if missing:
+            errors.append("compiled CSS is missing required utility classes: " + ", ".join(missing))
+    return emit_and_exit(result("maggie-css-utility-evidence.v1", errors, missingClasses=missing, checkedClasses=list(dict.fromkeys(classes))), Path(args.output) if args.output else None)
+
+
+def validate_dashboard(args: argparse.Namespace) -> int:
+    plan = read_json(Path(args.plan))
+    evidence = read_json(Path(args.evidence))
+    errors: list[str] = []
+    required = {"desktop", "tablet", "mobile", "collapsed-rail", "mobile-drawer", "modal"}
+    observed = set(evidence.get("screenshots") or []) | set(evidence.get("states") or [])
+    if plan.get("schemaVersion") != "maggie-dashboard-surface.v1":
+        errors.append("dashboard plan schemaVersion is invalid")
+    if not required <= observed:
+        errors.append("dashboard evidence is missing: " + ", ".join(sorted(required - observed)))
+    if evidence.get("route") != plan.get("route"):
+        errors.append("dashboard evidence route does not match plan")
+    return emit_and_exit(result("maggie-dashboard-surface.v1", errors, observed=sorted(observed)), Path(args.output) if args.output else None)
+
+
+def validate_sample(args: argparse.Namespace) -> int:
+    plan = read_json(Path(args.plan))
+    evidence = read_json(Path(args.evidence))
+    errors: list[str] = []
+    if plan.get("schemaVersion") != "maggie-sample-surface.v1":
+        errors.append("sample plan schemaVersion is invalid")
+    if evidence.get("noindex") is not True:
+        errors.append("sample route must be noindex")
+    if evidence.get("sitemapIncluded") is not False:
+        errors.append("sample route must be excluded from the sitemap")
+    if not str(evidence.get("banner") or "").strip():
+        errors.append("sample route needs an explicit layout-sample banner")
+    if not isinstance(evidence.get("placeholders"), list) or not evidence.get("placeholders"):
+        errors.append("sample evidence needs placeholder lines")
+    if not isinstance(evidence.get("finishChecklist"), list) or not evidence.get("finishChecklist"):
+        errors.append("sample evidence needs a finish checklist")
+    return emit_and_exit(result("maggie-sample-surface.v1", errors, route=plan.get("route")), Path(args.output) if args.output else None)
+
+
+def validate_privacy(args: argparse.Namespace) -> int:
+    evidence = read_json(Path(args.evidence))
+    errors: list[str] = []
+    if evidence.get("schemaVersion") != "maggie-privacy-origin-evidence.v1":
+        errors.append("evidence schemaVersion must be maggie-privacy-origin-evidence.v1")
+    observed: set[str] = set()
+    for page in evidence.get("pages") or []:
+        observed.update(str(origin) for origin in (page.get("origins") or []))
+    declared = set(str(origin) for origin in evidence.get("policyOrigins") or [])
+    if observed - declared:
+        errors.append("unlisted third-party origins: " + ", ".join(sorted(observed - declared)))
+    if declared - observed and evidence.get("requireObservedPolicyOrigins", True):
+        errors.append("privacy policy origins not observed in rendered pages: " + ", ".join(sorted(declared - observed)))
+    return emit_and_exit(result("maggie-privacy-origin-evidence.v1", errors, observedOrigins=sorted(observed), policyOrigins=sorted(declared)), Path(args.output) if args.output else None)
+
+
+def validate_structure(args: argparse.Namespace) -> int:
+    model = read_json(Path(args.model))
+    evidence = read_json(Path(args.evidence))
+    errors: list[str] = []
+    if model.get("schemaVersion") != "maggie-site-structure.v1":
+        errors.append("model schemaVersion must be maggie-site-structure.v1")
+    entries = {str(item.get("route")): item for item in model.get("pages") or [] if isinstance(item, dict) and item.get("route")}
+    seen = set()
+    for item in evidence.get("pages") or []:
+        if not isinstance(item, dict) or not item.get("route"):
+            errors.append("each rendered page evidence row needs a route")
+            continue
+        route = str(item["route"])
+        seen.add(route)
+        expected = entries.get(route)
+        if not expected:
+            errors.append(f"rendered route is absent from site structure model: {route}")
+            continue
+        for field in ("template", "source"):
+            if expected.get(field) != item.get(field):
+                errors.append(f"{route}: {field} does not match the model")
+        if set(expected.get("bands") or []) != set(item.get("bands") or []):
+            errors.append(f"{route}: band identities do not match the model")
+    for route in sorted(set(entries) - seen):
+        errors.append(f"model route has no rendered evidence: {route}")
+    return emit_and_exit(result("maggie-site-structure.v1", errors, checkedRoutes=sorted(seen)), Path(args.output) if args.output else None)
+
+
+def validate_capabilities(args: argparse.Namespace) -> int:
+    manifest = read_json(Path(args.manifest))
+    errors: list[str] = []
+    if manifest.get("schemaVersion") != "maggie-host-capabilities.v1":
+        errors.append("manifest schemaVersion must be maggie-host-capabilities.v1")
+    endpoints = manifest.get("endpoints")
+    if not isinstance(endpoints, list) or not endpoints:
+        errors.append("endpoints must be a non-empty array")
+        endpoints = []
+    seen: set[str] = set()
+    for endpoint in endpoints:
+        if not isinstance(endpoint, dict):
+            errors.append("each capability endpoint must be an object")
+            continue
+        ident = str(endpoint.get("id") or "")
+        if not ident or ident in seen:
+            errors.append("capability endpoint ids must be non-empty and unique")
+        seen.add(ident)
+        if not isinstance(endpoint.get("enabled"), bool):
+            errors.append(f"{ident or 'unknown'}: enabled must be boolean")
+        if not str(endpoint.get("path") or "").startswith("/"):
+            errors.append(f"{ident or 'unknown'}: path must start with /")
+    return emit_and_exit(result("maggie-host-capabilities.v1", errors, enabled=sum(1 for item in endpoints if isinstance(item, dict) and item.get("enabled") is True), endpointCount=len(endpoints)), Path(args.output) if args.output else None)
+
+
+def validate_style_editing(args: argparse.Namespace) -> int:
+    """Validate a closed, host-rendered style editing contract."""
+    manifest = read_json(Path(args.manifest))
+    errors: list[str] = []
+    if manifest.get("schemaVersion") != "maggie-style-editing.v1":
+        errors.append("manifest schemaVersion must be maggie-style-editing.v1")
+    properties = manifest.get("properties")
+    if not isinstance(properties, list) or not properties:
+        errors.append("properties must be a non-empty array")
+        properties = []
+    allowed: set[str] = set()
+    patterns: dict[str, str] = {}
+    dangerous = re.compile(r"(?:;|url\s*\(|expression\s*\(|<|>|javascript:)", re.I)
+    for item in properties:
+        if not isinstance(item, dict):
+            errors.append("each style property must be an object")
+            continue
+        name = str(item.get("name") or "")
+        pattern = str(item.get("pattern") or "")
+        if not re.fullmatch(r"[A-Za-z][A-Za-z0-9-]*", name):
+            errors.append(f"invalid style property name: {name or 'unknown'}")
+        if name in allowed:
+            errors.append(f"duplicate style property: {name}")
+        allowed.add(name)
+        if not pattern:
+            errors.append(f"style property {name or 'unknown'} needs a value pattern")
+        else:
+            try:
+                re.compile(pattern)
+                patterns[name] = pattern
+            except re.error:
+                errors.append(f"style property {name or 'unknown'} has an invalid value pattern")
+    for template in manifest.get("templates") or []:
+        if not isinstance(template, dict) or not str(template.get("id") or ""):
+            errors.append("each style template needs an id")
+            continue
+        for name, value in (template.get("styles") or {}).items():
+            if name not in allowed:
+                errors.append(f"style template {template['id']} uses undeclared property: {name}")
+                continue
+            if not isinstance(value, str) or dangerous.search(value) or not re.fullmatch(patterns[name], value):
+                errors.append(f"style template {template['id']} has an unsafe value for {name}")
+    return emit_and_exit(result("maggie-style-editing.v1", errors, properties=sorted(allowed), templates=len(manifest.get("templates") or [])), Path(args.output) if args.output else None)
+
+
+def validate_content_overrides(args: argparse.Namespace) -> int:
+    manifest = read_json(Path(args.manifest))
+    errors: list[str] = []
+    if manifest.get("schemaVersion") != "maggie-content-overrides.v1":
+        errors.append("manifest schemaVersion must be maggie-content-overrides.v1")
+    expected = {
+        "readAtRequestTime": True,
+        "sourceLiteralIsFallback": True,
+        "writesCreateRevision": True,
+        "conflictRequiresSourceRevision": True,
+        "orphanPolicy": "report-and-never-publish",
+    }
+    for key, value in expected.items():
+        if manifest.get(key) != value:
+            errors.append(f"{key} must be {value!r}")
+    if not isinstance(manifest.get("protectedFields"), list) or not manifest.get("protectedFields"):
+        errors.append("protectedFields must list factual fields that cannot be overridden")
+    return emit_and_exit(result("maggie-content-overrides.v1", errors, protectedFields=manifest.get("protectedFields", [])), Path(args.output) if args.output else None)
+
+
+def validate_session_contract(args: argparse.Namespace) -> int:
+    manifest = read_json(Path(args.manifest))
+    errors: list[str] = []
+    if manifest.get("schemaVersion") != "maggie-browser-session.v1":
+        errors.append("manifest schemaVersion must be maggie-browser-session.v1")
+    if manifest.get("mintingBoundary") != "host-adapter":
+        errors.append("mintingBoundary must be host-adapter")
+    if manifest.get("passwordHandling") != "never-exposed":
+        errors.append("passwordHandling must be never-exposed")
+    ttl = manifest.get("ttlMinutes")
+    if not isinstance(ttl, int) or not 1 <= ttl <= 240:
+        errors.append("ttlMinutes must be between 1 and 240")
+    for key in ("mintRoute", "revokeRoute"):
+        if not str(manifest.get(key) or "").startswith("/"):
+            errors.append(f"{key} must be a relative host route")
+    return emit_and_exit(result("maggie-browser-session.v1", errors, ttlMinutes=ttl), Path(args.output) if args.output else None)
+
+
+def validate_cache_boundary(args: argparse.Namespace) -> int:
+    evidence = read_json(Path(args.evidence))
+    errors: list[str] = []
+    if evidence.get("schemaVersion") != "maggie-public-session-cache.v1":
+        errors.append("evidence schemaVersion must be maggie-public-session-cache.v1")
+    if evidence.get("publicHtmlVariesBySession") is not False:
+        errors.append("publicHtmlVariesBySession must be false")
+    if evidence.get("sessionCookieHttpOnly") is not True:
+        errors.append("sessionCookieHttpOnly must be true")
+    if evidence.get("identityHintCookieReadable") is not True:
+        errors.append("identityHintCookieReadable must be true")
+    if evidence.get("identityRequestWhenHintAbsent") is not False:
+        errors.append("identityRequestWhenHintAbsent must be false")
+    return emit_and_exit(result("maggie-public-session-cache.v1", errors), Path(args.output) if args.output else None)
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(prog="maggie contracts")
+    sub = parser.add_subparsers(dest="command", required=True)
+    progressive = sub.add_parser("progressive-check")
+    progressive.add_argument("--evidence", required=True); progressive.add_argument("--output")
+    progressive.set_defaults(func=validate_progressive)
+    css = sub.add_parser("css-check")
+    css.add_argument("--evidence"); css.add_argument("--html"); css.add_argument("--css"); css.add_argument("--required-class", action="append", default=[]); css.add_argument("--output")
+    css.set_defaults(func=validate_css)
+    cascade = sub.add_parser("css-cascade-check")
+    cascade.add_argument("--evidence", required=True); cascade.add_argument("--output")
+    cascade.set_defaults(func=validate_css)
+    dash_init = sub.add_parser("dash-init")
+    dash_init.add_argument("--project", default="."); dash_init.add_argument("--route", required=True); dash_init.add_argument("--confirm", action="store_true")
+    dash_init.set_defaults(func=lambda args: init_plan(args, "dashboard", {"route": args.route, "operatorJourneys": ["first-person task completion"], "shell": {"rail": True, "workArea": True, "tabs": True, "modal": True}, "requiredEvidence": ["desktop", "tablet", "mobile", "collapsed-rail", "mobile-drawer", "modal"], "publicWrite": False}))
+    dash_validate = sub.add_parser("dash-validate")
+    dash_validate.add_argument("--plan", required=True); dash_validate.add_argument("--evidence", required=True); dash_validate.add_argument("--output")
+    dash_validate.set_defaults(func=validate_dashboard)
+    sample_init = sub.add_parser("sample-init")
+    sample_init.add_argument("--project", default="."); sample_init.add_argument("--route", required=True); sample_init.add_argument("--purpose", required=True); sample_init.add_argument("--confirm", action="store_true")
+    sample_init.set_defaults(func=lambda args: init_plan(args, "sample", {"route": args.route, "purpose": args.purpose, "noindex": True, "sitemapIncluded": False, "bannerRequired": True, "placeholderPolicy": "unwritten lines must remain explicit placeholders", "finishChecklist": ["replace placeholder copy", "replace media", "run accessibility and SEO checks"], "publicWrite": False}))
+    sample_validate = sub.add_parser("sample-validate")
+    sample_validate.add_argument("--plan", required=True); sample_validate.add_argument("--evidence", required=True); sample_validate.add_argument("--output")
+    sample_validate.set_defaults(func=validate_sample)
+    privacy = sub.add_parser("privacy-check")
+    privacy.add_argument("--evidence", required=True); privacy.add_argument("--output")
+    privacy.set_defaults(func=validate_privacy)
+    structure = sub.add_parser("structure-validate")
+    structure.add_argument("--model", required=True); structure.add_argument("--evidence", required=True); structure.add_argument("--output")
+    structure.set_defaults(func=validate_structure)
+    capabilities = sub.add_parser("capabilities-validate")
+    capabilities.add_argument("--manifest", required=True); capabilities.add_argument("--output")
+    capabilities.set_defaults(func=validate_capabilities)
+    style = sub.add_parser("style-check")
+    style.add_argument("--manifest", required=True); style.add_argument("--output")
+    style.set_defaults(func=validate_style_editing)
+    overrides = sub.add_parser("content-overrides-check")
+    overrides.add_argument("--manifest", required=True); overrides.add_argument("--output")
+    overrides.set_defaults(func=validate_content_overrides)
+    session = sub.add_parser("session-check")
+    session.add_argument("--manifest", required=True); session.add_argument("--output")
+    session.set_defaults(func=validate_session_contract)
+    cache = sub.add_parser("cache-boundary-check")
+    cache.add_argument("--evidence", required=True); cache.add_argument("--output")
+    cache.set_defaults(func=validate_cache_boundary)
+    args = parser.parse_args()
+    try:
+        return args.func(args)
+    except (OSError, ValueError, json.JSONDecodeError) as error:
+        print(f"BLOCKED: maggie contract validation: {error}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/bundled-tools/clis/maggie_dash.py

@@ -192,9 +192,10 @@ def merge_astro_middleware(path: Path) -> dict[str, object]:
     """Add the stable Maggie paths to an existing conventional Astro middleware.
 
     The installer must preserve host-owned auth/redirect logic. This narrow
-    merge only handles the common `onRequest = defineMiddleware((context,
-    next) => { ... })` shape and is idempotent. Unknown middleware shapes are
-    reported to the caller instead of being rewritten heuristically.
+    merge handles the common `onRequest = defineMiddleware((context, next) =>
+    { ... })` shape and the equivalent destructured context form. Unknown
+    middleware shapes are reported to the caller instead of being rewritten
+    heuristically.
     """
     try:
         content = path.read_text(encoding="utf-8")
@@ -209,8 +210,6 @@ def merge_astro_middleware(path: Path) -> dict[str, object]:
         r"export\s+const\s+onRequest\s*=\s*defineMiddleware\(\s*\(\s*context\s*,\s*next\s*\)\s*=>\s*\{",
         content,
     )
-    if not match:
-        return {"status": "manual", "reason": "middleware is not the supported defineMiddleware((context, next) => {}) shape"}
     block = r'''
   // maggie-auto-rewrite-v1: generated by `maggie booking install`; keep host auth below.
   const maggieRewrites: Array<[RegExp, (path: string) => string]> = [
@@ -228,7 +227,24 @@ def merge_astro_middleware(path: Path) -> dict[str, object]:
     }
   }
 '''
-    merged = content[:match.end()] + block + content[match.end():]
+    if match:
+        merged = content[:match.end()] + block + content[match.end():]
+    else:
+        # Astro examples commonly destructure the request context in the
+        # parameter list: `(({ url, request }, next) => { ... })`. Normalize
+        # only this explicit shape so the generated rewrite block can use the
+        # full context while preserving the host's existing variable names.
+        destructured = re.search(
+            r"(?P<prefix>export\s+const\s+onRequest\s*=\s*defineMiddleware\(\s*\()\s*\{(?P<properties>[^{}]+)\}\s*,\s*(?P<next>[A-Za-z_$][\w$]*)\s*\)\s*=>\s*\{",
+            content,
+        )
+        if not destructured:
+            return {"status": "manual", "reason": "middleware is not a supported defineMiddleware((context, next) => {}) shape"}
+        properties = destructured.group("properties").strip()
+        next_name = destructured.group("next")
+        replacement = f"{destructured.group('prefix')}context, {next_name}) => {{\n  const {{ {properties} }} = context;"
+        normalized = content[:destructured.start()] + replacement + content[destructured.end():]
+        merged = normalized[:destructured.start() + len(replacement)] + block + normalized[destructured.start() + len(replacement):]
     try:
         path.write_text(merged, encoding="utf-8")
     except OSError as error:

package/bundled-tools/clis/maggie_design.py

@@ -10,6 +10,7 @@ from __future__ import annotations
 
 import argparse
 import hashlib
+import html as html_lib
 import json
 import re
 import shutil
@@ -82,6 +83,50 @@ def rendered_asset_preflight(template: Path) -> list[str]:
     return errors
 
 
+def source_anchor_start(source: str, tag: str, reported_offset: int) -> int:
+    """Resolve an Astro compiler offset to the opening bracket of an element."""
+    if not re.fullmatch(r"[A-Za-z][A-Za-z0-9:-]*", tag):
+        raise ValueError("tag name is invalid")
+    bound = max(0, min(len(source), int(reported_offset) + 1))
+    start = source.rfind("<" + tag, 0, bound)
+    if start < 0:
+        raise ValueError(f"opening tag not found near compiler offset: {tag}")
+    return start
+
+
+def decode_content_text(value: str) -> str:
+    """Decode markup entities once and refuse unknown/double-escaped entities."""
+    decoded = html_lib.unescape(value)
+    if re.search(r"&(?:[A-Za-z][A-Za-z0-9]+|#\d+|#x[0-9A-Fa-f]+);", decoded):
+        raise ValueError("text contains an unknown or double-escaped HTML entity")
+    return decoded
+
+
+def markup_check(html_path: Path, require_keys: bool) -> int:
+    source = html_path.read_text(encoding="utf-8")
+    errors: list[str] = []
+    if re.search(r"\bstyle\s*=\s*([\"'])\s*\1", source, re.I):
+        errors.append("empty style attributes must be omitted")
+    keys = re.findall(r"\bdata-maggie-content-key\s*=\s*[\"']([^\"']+)[\"']", source, re.I)
+    duplicates = sorted({key for key in keys if keys.count(key) > 1})
+    if duplicates:
+        errors.append("duplicate content keys: " + ", ".join(duplicates))
+    if require_keys:
+        for match in re.finditer(r"<(p|h[1-6]|li|button|a|span)\b([^>]*)>([^<>]+)</\1>", source, re.I | re.S):
+            attrs, text = match.group(2), " ".join(match.group(3).split())
+            if text and not re.search(r"\bdata-maggie-content-key\s*=", attrs, re.I):
+                errors.append(f"editable text node lacks data-maggie-content-key: {match.group(1)}")
+            try:
+                decode_content_text(match.group(3))
+            except ValueError as error:
+                errors.append(str(error))
+    result = {"schemaVersion": "maggie-design-markup.v1", "passed": not errors,
+              "errors": errors, "contentKeyCount": len(keys), "requireKeys": require_keys,
+              "source": str(html_path.resolve())}
+    print(json.dumps(result, indent=2, ensure_ascii=False))
+    return 0 if not errors else 1
+
+
 def _surface_list(value: str) -> list[str]:
     surfaces = [item.strip().lower() for item in value.split(",") if item.strip()]
     invalid = sorted(set(surfaces) - set(REFERENCE_SURFACES))
@@ -532,9 +577,31 @@ def design_job_path(project: Path, job_id: str) -> Path:
     return project / ".maggie" / "design-jobs" / f"{job_id}.json"
 
 
-def save_design_job(project: Path, job: dict[str, object]) -> None:
+def design_job_candidates(project: Path, job_id: str) -> list[Path]:
+    """Return every supported location for a resumable design job.
+
+    In-place jobs historically live under ``design-jobs`` while first-party
+    author jobs are briefs under ``.maggie/design``. Both are Maggie design
+    jobs and the progress commands must treat them identically.
+    """
+    root = project.resolve() / ".maggie"
+    return [
+        root / "design-jobs" / f"{job_id}.json",
+        root / "design" / f"{job_id}.json",
+    ]
+
+
+def find_design_job_path(project: Path, job_id: str) -> Path:
+    for candidate in design_job_candidates(project, job_id):
+        if candidate.is_file():
+            return candidate
+    expected = design_job_path(project.resolve(), job_id)
+    raise ValueError(f"design job not found: {expected}")
+
+
+def save_design_job(project: Path, job: dict[str, object], path: Path | None = None) -> None:
     job["updated_at"] = datetime.now(timezone.utc).isoformat()
-    path = design_job_path(project, str(job["id"]))
+    path = path or design_job_path(project, str(job["id"]))
     path.parent.mkdir(parents=True, exist_ok=True)
     path.write_text(json.dumps(job, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
 
@@ -599,17 +666,13 @@ def run_design_job(urls: list[str], project: Path, clone_run: str, force: bool =
 
 
 def design_status(project: Path, job_id: str) -> int:
-    path = design_job_path(project.resolve(), job_id)
-    if not path.exists():
-        raise ValueError(f"design job not found: {path}")
+    path = find_design_job_path(project, job_id)
     print(path.read_text(encoding="utf-8"), end="")
     return 0
 
 
 def design_resume(project: Path, job_id: str) -> int:
-    path = design_job_path(project.resolve(), job_id)
-    if not path.exists():
-        raise ValueError(f"design job not found: {path}")
+    path = find_design_job_path(project, job_id)
     job = json.loads(path.read_text(encoding="utf-8"))
     return run_design_job(job["urls"], project, job["clone_run"], force=True)[0]
 
@@ -620,9 +683,7 @@ def _step_records(names: list[str]) -> list[dict[str, object]]:
 
 def design_step(project: Path, job_id: str, step: str, evidence: str) -> int:
     """Record one piece of implementation evidence and make progress durable."""
-    path = design_job_path(project.resolve(), job_id)
-    if not path.exists():
-        raise ValueError(f"design job not found: {path}")
+    path = find_design_job_path(project, job_id)
     job = json.loads(path.read_text(encoding="utf-8"))
     steps = job.get("steps", [])
     target = next((item for item in steps if item.get("name") == step), None)
@@ -774,8 +835,9 @@ def author_job(project: Path, route: str, purpose: str, audience: str, brief_fil
     brief = {"schemaVersion": "maggie-page-brief.v1", "route": route, "purpose": purpose.strip() or source_brief["purpose"], "audience": audience.strip() or source_brief["audience"], "contentBrief": source_brief.get("contentBrief", ""), "shell": "homepage-canonical", "status": "draft", "sourceEvidence": None, "approval": {"status": "pending", "actor": None}, "createdAt": datetime.now(timezone.utc).isoformat()}
     digest = hashlib.sha256((str(project) + "\n" + route).encode()).hexdigest()[:12]
     output = project / ".maggie" / "design" / "briefs" / f"{relative.replace('/', '-')}.json"; output.parent.mkdir(parents=True, exist_ok=True); output.write_text(json.dumps(brief, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+    required_steps = ["inspect-shell", "implement-page", "capture-responsive-screenshots", "accessibility-check", "build-check", "approval"]
     plan_path = project / ".maggie" / "design" / f"author-{digest}.json"
-    plan_path.write_text(json.dumps({"id": f"author-{digest}", "workflow": "maggie-design", "mode": "author", "phase": "ready", "brief": str(output), "designContract": contract, "sourceUrlRequired": False, "shellSourceOfTruth": "homepage-canonical", "approvalRequired": True, "requiredSteps": ["inspect-shell", "implement-page", "capture-responsive-screenshots", "accessibility-check", "build-check", "approval"]}, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+    plan_path.write_text(json.dumps({"id": f"author-{digest}", "workflow": "maggie-design", "mode": "author", "phase": "ready", "brief": str(output), "designContract": contract, "sourceUrlRequired": False, "shellSourceOfTruth": "homepage-canonical", "approvalRequired": True, "requiredSteps": required_steps, "required_steps": required_steps, "steps": _step_records(required_steps), "history": [{"phase": "ready", "at": datetime.now(timezone.utc).isoformat()}]}, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
     print(json.dumps({"brief": str(output), "plan": str(plan_path), "phase": "ready"}, indent=2)); return 0
 
 
@@ -791,6 +853,7 @@ commands:
   status       show a design job and its per-step progress
   resume       restart a failed design workflow
   author       plan an original first-party page
+  markup-check validate optional style attributes, content keys, and entities
   reference-ui, init, validate-ui, app-init, app-validate, rebrand, review
 """)
         return 0
@@ -806,6 +869,15 @@ commands:
             return reference_ui(args.project, args.reference, _surface_list(args.surface), args.screenshots_dir, args.confirm)
         except (OSError, ValueError, json.JSONDecodeError) as error:
             print(f"BLOCKED: maggie-design reference-ui: {error}", file=sys.stderr); return 1
+    if len(sys.argv) > 1 and sys.argv[1] == "markup-check":
+        command = argparse.ArgumentParser(description="Validate generated markup before it is made editable.")
+        command.add_argument("--html", type=Path, required=True)
+        command.add_argument("--require-content-keys", action="store_true")
+        args = command.parse_args(sys.argv[2:])
+        try:
+            return markup_check(args.html, args.require_content_keys)
+        except (OSError, ValueError) as error:
+            print(f"BLOCKED: maggie-design markup-check: {error}", file=sys.stderr); return 1
     if len(sys.argv) > 1 and sys.argv[1] == "init":
         command = argparse.ArgumentParser(description="Initialize a native blog or service UI plan from a sanitized reference manifest.")
         command.add_argument("--project", type=Path, default=Path.cwd())