@topy-ai/maggie 0.7.48 → 0.7.49

package/bundled-tools/clis/maggie_design_verify.py

@@ -0,0 +1,359 @@
+#!/usr/bin/env python3
+"""Orchestrate evidence for a Maggie design job and record completed steps.
+
+``maggie design verify JOB_ID`` runs every *automatable* step of an in-place,
+section-scoped, or author design job against a host adapter — a running
+server (``--base-url``) or a static build (``--dist``) — writes durable
+evidence under ``.maggie/design-evidence/<job>/``, and records a step as done
+only when its check passed. Steps that need an implementer or a person
+(``apply-design-contract``, ``implement-*``, ``visual-review``, ``approval``)
+are never completed here; record them with ``maggie design step`` and real
+evidence. A job therefore cannot reach ``done`` without evidence.
+
+Section jobs are two-stage: run ``--stage before`` before editing (captures the
+section snapshot) and the default ``--stage after`` once implemented.
+"""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import re
+import subprocess
+import sys
+from datetime import datetime, timezone
+from html.parser import HTMLParser
+from pathlib import Path
+from urllib.parse import urlsplit
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+
+from maggie_design import REVIEW_VIEWPORTS, find_design_job_path, validate_section_evidence  # noqa: E402
+from maggie_icon_glyph_check import _ProbeServer, find_chrome  # noqa: E402
+
+SCHEMA = "maggie-design-verify.v1"
+MANUAL_STEPS = {"apply-design-contract", "implement-section", "implement-page", "visual-review", "approval"}
+INSPECT_STEPS = {"inspect-route", "inspect-shell", "inspect-section"}
+PLACEHOLDERS = re.compile(r"\{\{[^}]*\}\}|\[object Object\]|\bundefined\b|lorem ipsum", re.I)
+VOID_TAGS = {"area", "base", "br", "col", "embed", "hr", "img", "input", "link", "meta", "source", "track", "wbr"}
+
+
+def now() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+class PageFacts(HTMLParser):
+    """Collect bounded structural facts and per-section hashes from HTML."""
+
+    def __init__(self) -> None:
+        super().__init__(convert_charrefs=True)
+        self.title = ""; self._in_title = False; self.lang = ""
+        self.h1 = 0; self.landmarks: set[str] = set(); self.ids: set[str] = set()
+        self.images_without_alt = 0; self.unnamed_controls = 0; self.unlabelled_inputs = 0
+        self.robots_noindex = False; self.text_parts: list[str] = []
+        self._labels_for: set[str] = set(); self._input_ids: list[tuple[str, bool]] = []
+        self._control_stack: list[dict] = []; self._label_depth = 0
+        self.sections: dict[str, list[str]] = {}; self._open_sections: list[tuple[str, int]] = []; self._depth = 0
+
+    def _section_id(self, tag: str, attrs: dict[str, str]) -> str | None:
+        explicit = attrs.get("data-section-id") or attrs.get("data-maggie-section")
+        if explicit:
+            return explicit
+        return attrs.get("id") if tag == "section" and attrs.get("id") else None
+
+    def _record(self, token: str) -> None:
+        for section_id, _depth in self._open_sections:
+            self.sections[section_id].append(token)
+
+    def handle_starttag(self, tag: str, attr_list: list[tuple[str, str | None]]) -> None:
+        attrs = {name: value or "" for name, value in attr_list}
+        void = tag in VOID_TAGS
+        if not void:
+            self._depth += 1
+        section_id = self._section_id(tag, attrs)
+        if section_id and not void:
+            self.sections.setdefault(section_id, [])
+            self._open_sections.append((section_id, self._depth))
+        self._record("<" + tag + "".join(f" {k}={v}" for k, v in sorted(attrs.items()) if k not in {"nonce"}) + ">")
+        if attrs.get("id"):
+            self.ids.add(attrs["id"])
+        if tag == "html":
+            self.lang = attrs.get("lang", "")
+        elif tag == "title":
+            self._in_title = True
+        elif tag == "h1":
+            self.h1 += 1
+        elif tag in {"header", "main", "footer", "nav"}:
+            self.landmarks.add(tag)
+        elif tag == "meta" and attrs.get("name", "").lower() == "robots" and "noindex" in attrs.get("content", "").lower():
+            self.robots_noindex = True
+        elif tag == "img" and "alt" not in attrs:
+            self.images_without_alt += 1
+        elif tag == "label":
+            self._label_depth += 1
+            if attrs.get("for"):
+                self._labels_for.add(attrs["for"])
+        elif tag in {"input", "select", "textarea"} and attrs.get("type", "").lower() not in {"hidden", "submit", "button", "reset", "image"}:
+            named = bool(attrs.get("aria-label") or attrs.get("aria-labelledby") or attrs.get("title") or self._label_depth)
+            self._input_ids.append((attrs.get("id", ""), named))
+        if tag in {"a", "button"} and not void:
+            named = bool(attrs.get("aria-label") or attrs.get("aria-labelledby") or attrs.get("title"))
+            self._control_stack.append({"tag": tag, "named": named, "text": ""})
+        if tag == "img" and self._control_stack and attrs.get("alt"):
+            self._control_stack[-1]["named"] = True
+
+    def handle_endtag(self, tag: str) -> None:
+        self._record("</" + tag + ">")
+        if tag == "title":
+            self._in_title = False
+        elif tag == "label" and self._label_depth:
+            self._label_depth -= 1
+        if tag in {"a", "button"} and self._control_stack and self._control_stack[-1]["tag"] == tag:
+            control = self._control_stack.pop()
+            if not control["named"] and not control["text"].strip():
+                self.unnamed_controls += 1
+        if tag not in VOID_TAGS:
+            while self._open_sections and self._open_sections[-1][1] >= self._depth:
+                self._open_sections.pop()
+            self._depth = max(0, self._depth - 1)
+
+    def handle_data(self, data: str) -> None:
+        if self._in_title:
+            self.title += data
+        text = " ".join(data.split())
+        if text:
+            self._record(text)
+            self.text_parts.append(text)
+            for control in self._control_stack:
+                control["text"] += text
+
+    def finish(self) -> dict:
+        unlabelled = sum(1 for input_id, named in self._input_ids if not named and not (input_id and input_id in self._labels_for))
+        return {
+            "title": self.title.strip()[:200], "lang": self.lang, "h1Count": self.h1, "landmarks": sorted(self.landmarks),
+            "imagesWithoutAlt": self.images_without_alt, "unnamedControls": self.unnamed_controls, "unlabelledInputs": unlabelled,
+            "robotsNoindex": self.robots_noindex,
+            "placeholders": sorted({match.group(0)[:40] for match in PLACEHOLDERS.finditer(" ".join(self.text_parts))}),
+            "sections": [{"id": section_id, "hash": hashlib.sha256("\n".join(tokens).encode("utf-8")).hexdigest(), "tokens": len(tokens)} for section_id, tokens in sorted(self.sections.items())],
+        }
+
+
+def page_facts(document: str) -> dict:
+    parser = PageFacts()
+    parser.feed(document)
+    parser.close()
+    return parser.finish()
+
+
+def job_routes(job: dict) -> list[str]:
+    if isinstance(job.get("routes"), list) and job["routes"]:
+        return [item["route"] if isinstance(item, dict) else str(item) for item in job["routes"]]
+    if job.get("route"):
+        return [str(job["route"])]
+    if job.get("brief") and Path(job["brief"]).is_file():
+        return [json.loads(Path(job["brief"]).read_text(encoding="utf-8"))["route"]]
+    raise ValueError("design job has no routes to verify")
+
+
+class Verifier:
+    def __init__(self, project: Path, job_id: str, server: _ProbeServer, chrome: str | None, stage: str, build_command: str | None, budget_ms: int) -> None:
+        self.project = project; self.job_id = job_id; self.server = server; self.chrome = chrome
+        self.stage = stage; self.build_command = build_command; self.budget_ms = budget_ms
+        self.job_path = find_design_job_path(project, job_id)
+        self.job = json.loads(self.job_path.read_text(encoding="utf-8"))
+        self.routes = job_routes(self.job)
+        self.evidence_dir = project / ".maggie" / "design-evidence" / job_id
+        self.evidence_dir.mkdir(parents=True, exist_ok=True)
+        self._pages: dict[str, tuple[int, str, str]] = {}
+
+    def page(self, route: str) -> tuple[int, str, str]:
+        if route not in self._pages:
+            status, content_type, body = self.server.fetch(route)
+            self._pages[route] = (status, content_type, body.decode("utf-8", errors="replace"))
+        return self._pages[route]
+
+    def rendered(self, route: str) -> str:
+        if not self.chrome:
+            return self.page(route)[2]
+        proc = subprocess.run([self.chrome, "--headless=new", "--no-sandbox", "--disable-gpu", f"--virtual-time-budget={self.budget_ms}", "--dump-dom", self.server.origin + route], capture_output=True, text=True, timeout=180, check=False)
+        return proc.stdout if proc.returncode == 0 and proc.stdout.strip() else self.page(route)[2]
+
+    def write(self, name: str, payload: dict) -> Path:
+        path = self.evidence_dir / f"{name}.json"
+        path.write_text(json.dumps(payload, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+        return path
+
+    # -- step checks: return (passed, evidence payload) ----------------------
+
+    def inspect(self, step: str) -> tuple[bool, dict]:
+        results, errors = [], []
+        for route in self.routes:
+            status, content_type, document = self.page(route)
+            facts = page_facts(document) if "html" in content_type else {}
+            results.append({"route": route, "status": status, "contentType": content_type.split(";")[0], "title": facts.get("title"), "landmarks": facts.get("landmarks"), "sectionIds": [item["id"] for item in facts.get("sections", [])], "sha256": hashlib.sha256(document.encode("utf-8")).hexdigest()})
+            if not 200 <= status <= 299 or "html" not in content_type:
+                errors.append(f"{route}: HTTP {status} {content_type.split(';')[0]}")
+            if step == "inspect-shell" and not {"header", "footer"} <= set(facts.get("landmarks", [])):
+                errors.append(f"{route}: canonical shell needs header and footer landmarks")
+            if step == "inspect-section" and self.job.get("sectionId") not in {item["id"] for item in facts.get("sections", [])}:
+                errors.append(f"{route}: section {self.job.get('sectionId')!r} not found (use <section id> or data-section-id)")
+        return not errors, {"routes": results, "errors": errors}
+
+    def declare_content_source(self) -> tuple[bool, dict]:
+        routes = [item for item in self.job.get("routes", []) if isinstance(item, dict)]
+        unproven = [item["route"] for item in routes if item.get("resolution") == "unproven"]
+        return not unproven and bool(routes), {"routes": [{key: item.get(key) for key in ("route", "resolution", "contentSource")} for item in routes], "errors": [f"{route}: catch-all content source not declared; recreate the job with --content-source" for route in unproven]}
+
+    def snapshot(self, label: str) -> tuple[bool, dict]:
+        route = self.routes[0]
+        status, _content_type, _document = self.page(route)
+        facts = page_facts(self.rendered(route))
+        payload = {"schemaVersion": "maggie-section-snapshot.v1", "route": route, "status": status, "label": label, "sections": [{"id": item["id"], "hash": item["hash"]} for item in facts["sections"]]}
+        errors = [] if 200 <= status <= 299 and payload["sections"] else [f"{route}: no sections captured (HTTP {status})"]
+        payload["errors"] = errors
+        return not errors, payload
+
+    def unchanged_rest(self) -> tuple[bool, dict]:
+        before = self.evidence_dir / "capture-before.json"
+        after = self.evidence_dir / "capture-after.json"
+        if not before.is_file() or not after.is_file():
+            return False, {"errors": ["capture-before and capture-after evidence are both required; run --stage before first"]}
+        result = validate_section_evidence(before, after, str(self.job.get("sectionId")))
+        return bool(result["passed"]), result
+
+    def screenshots(self) -> tuple[bool, dict]:
+        if not self.chrome:
+            return False, {"errors": ["google-chrome or chromium is required for screenshots"]}
+        shots, errors = [], []
+        for route in self.routes:
+            slug = re.sub(r"[^a-z0-9]+", "-", route.lower()).strip("-") or "home"
+            for viewport, (width, height) in REVIEW_VIEWPORTS.items():
+                target = self.evidence_dir / "screenshots" / f"{slug}-{viewport}.png"
+                target.parent.mkdir(parents=True, exist_ok=True)
+                proc = subprocess.run([self.chrome, "--headless=new", "--no-sandbox", "--disable-gpu", "--hide-scrollbars", f"--window-size={width},{height}", f"--virtual-time-budget={self.budget_ms}", f"--screenshot={target}", self.server.origin + route], capture_output=True, text=True, timeout=180, check=False)
+                if proc.returncode != 0 or not target.is_file() or target.stat().st_size == 0:
+                    errors.append(f"{route} @ {viewport}: screenshot failed")
+                    continue
+                shots.append({"route": route, "viewport": viewport, "size": [width, height], "path": str(target), "sha256": hashlib.sha256(target.read_bytes()).hexdigest()})
+        return not errors and bool(shots), {"screenshots": shots, "errors": errors}
+
+    def accessibility(self) -> tuple[bool, dict]:
+        results, errors = [], []
+        for route in self.routes:
+            facts = page_facts(self.rendered(route))
+            item = {key: facts[key] for key in ("lang", "h1Count", "imagesWithoutAlt", "unnamedControls", "unlabelledInputs", "landmarks")}
+            item["route"] = route
+            results.append(item)
+            if not facts["lang"]: errors.append(f"{route}: <html> has no lang")
+            if facts["h1Count"] != 1: errors.append(f"{route}: expected exactly one h1, found {facts['h1Count']}")
+            if facts["imagesWithoutAlt"]: errors.append(f"{route}: {facts['imagesWithoutAlt']} image(s) without alt")
+            if facts["unnamedControls"]: errors.append(f"{route}: {facts['unnamedControls']} link/button(s) without an accessible name")
+            if facts["unlabelledInputs"]: errors.append(f"{route}: {facts['unlabelledInputs']} form field(s) without a label")
+            if "main" not in facts["landmarks"]: errors.append(f"{route}: no <main> landmark")
+        return not errors, {"routes": results, "errors": errors, "scope": "static rendered-DOM checks; not a substitute for assistive-technology testing"}
+
+    def route_validation(self) -> tuple[bool, dict]:
+        results, errors = [], []
+        for route in self.routes:
+            status, content_type, _document = self.page(route)
+            facts = page_facts(self.rendered(route)) if "html" in content_type else {"title": "", "h1Count": 0, "placeholders": [], "robotsNoindex": False}
+            results.append({"route": route, "status": status, "title": facts["title"], "h1Count": facts["h1Count"], "placeholders": facts["placeholders"], "robotsNoindex": facts["robotsNoindex"]})
+            if not 200 <= status <= 299: errors.append(f"{route}: HTTP {status}")
+            if not facts["title"]: errors.append(f"{route}: empty <title>")
+            if facts["h1Count"] < 1: errors.append(f"{route}: no h1")
+            if facts["placeholders"]: errors.append(f"{route}: unresolved placeholder text {facts['placeholders']}")
+            if facts["robotsNoindex"]: errors.append(f"{route}: robots noindex present")
+        return not errors, {"routes": results, "errors": errors}
+
+    def build(self) -> tuple[bool, dict] | None:
+        if not self.build_command:
+            return None
+        proc = subprocess.run(self.build_command, shell=True, cwd=self.project, capture_output=True, text=True, timeout=1800, check=False)
+        tail = (proc.stdout + proc.stderr)[-2000:]
+        return proc.returncode == 0, {"command": self.build_command, "exitCode": proc.returncode, "outputTail": tail, "errors": [] if proc.returncode == 0 else [f"build exited {proc.returncode}"]}
+
+    def check(self, step: str) -> tuple[bool, dict] | None:
+        if step in INSPECT_STEPS: return self.inspect(step)
+        if step == "declare-content-source": return self.declare_content_source()
+        if step == "capture-before": return self.snapshot("before") if self.stage == "before" else None
+        if step == "capture-after": return self.snapshot("after") if self.stage == "after" else None
+        if step == "assert-unchanged-rest": return self.unchanged_rest() if self.stage == "after" else None
+        if step == "capture-responsive-screenshots": return self.screenshots()
+        if step == "accessibility-check": return self.accessibility()
+        if step == "route-validation": return self.route_validation()
+        if step == "build-check": return self.build()
+        return None
+
+    def run(self, recheck: bool) -> dict:
+        steps = self.job.get("steps") or []
+        report_steps = []
+        for step in steps:
+            name = str(step.get("name"))
+            if step.get("status") == "done" and not recheck:
+                report_steps.append({"step": name, "status": "done", "evidence": step.get("evidence"), "action": "kept"})
+                continue
+            if name in MANUAL_STEPS:
+                report_steps.append({"step": name, "status": step.get("status", "pending"), "action": "requires implementer or reviewer evidence: maggie design step " + self.job_id + f" --step {name} --evidence FILE"})
+                continue
+            outcome = self.check(name)
+            if outcome is None:
+                reason = "not part of this stage" if name in {"capture-before", "capture-after", "assert-unchanged-rest"} else ("pass --build-command to run the host build" if name == "build-check" else "no automated check for this step")
+                report_steps.append({"step": name, "status": step.get("status", "pending"), "action": reason})
+                continue
+            passed, payload = outcome
+            payload = {"schemaVersion": "maggie-design-step-evidence.v1", "jobId": self.job_id, "step": name, "passed": passed, "checkedAt": now(), **payload}
+            path = self.write(name, payload)
+            if passed:
+                step.update({"status": "done", "evidence": str(path), "completedAt": now(), "verifiedBy": "maggie design verify"})
+                self.job.setdefault("history", []).append({"event": "step-completed", "step": name, "evidence": str(path), "at": now(), "verifiedBy": "maggie design verify"})
+            else:
+                step["lastCheck"] = {"passed": False, "evidence": str(path), "at": now()}
+            report_steps.append({"step": name, "status": step.get("status", "pending"), "action": "verified" if passed else "failed", "evidence": str(path), "errors": payload.get("errors", [])[:10]})
+        self.job["phase"] = "done" if steps and all(item.get("status") == "done" for item in steps) else "ready"
+        self.job["updated_at"] = now()
+        self.job_path.write_text(json.dumps(self.job, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+        failed = [item["step"] for item in report_steps if item.get("action") == "failed"]
+        pending = [item["step"] for item in report_steps if item.get("status") != "done"]
+        return {"schemaVersion": SCHEMA, "jobId": self.job_id, "mode": self.job.get("mode"), "stage": self.stage, "routes": self.routes, "phase": self.job["phase"], "passed": not failed, "failedSteps": failed, "pendingSteps": pending, "steps": report_steps, "evidenceDir": str(self.evidence_dir), "mutation": "job step records only"}
+
+
+def verify(project: Path, job_id: str, base_url: str | None, dist: Path | None, stage: str, build_command: str | None, recheck: bool, budget_ms: int, require_browser: bool) -> dict:
+    if bool(base_url) == bool(dist):
+        raise ValueError("exactly one of --base-url or --dist is required")
+    if base_url and urlsplit(base_url).scheme not in {"http", "https"}:
+        raise ValueError("--base-url must be http(s)")
+    try:
+        chrome: str | None = find_chrome()
+    except RuntimeError:
+        if require_browser:
+            raise
+        chrome = None
+    with _ProbeServer("", base_url=base_url, dist=dist) as server:
+        verifier = Verifier(project.resolve(), job_id, server, chrome, stage, build_command, budget_ms)
+        return verifier.run(recheck)
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="maggie design verify", description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    parser.add_argument("job_id")
+    parser.add_argument("--project", type=Path, default=Path.cwd())
+    parser.add_argument("--base-url", help="running host origin (GET-only)")
+    parser.add_argument("--dist", type=Path, help="static build directory")
+    parser.add_argument("--stage", choices=("before", "after"), default="after", help="section jobs: capture before editing, then verify after")
+    parser.add_argument("--build-command", help="explicit host build command for the build-check step")
+    parser.add_argument("--recheck", action="store_true", help="re-run steps that are already done")
+    parser.add_argument("--budget-ms", type=int, default=6000)
+    parser.add_argument("--require-browser", action="store_true", help="fail instead of falling back to static HTML when Chrome is unavailable")
+    args = parser.parse_args(argv)
+    try:
+        report = verify(args.project, args.job_id, args.base_url, args.dist, args.stage, args.build_command, args.recheck, args.budget_ms, args.require_browser)
+    except (OSError, ValueError, RuntimeError, json.JSONDecodeError) as error:
+        print(f"BLOCKED: maggie-design verify: {error}", file=sys.stderr)
+        return 2
+    print(json.dumps(report, indent=2, ensure_ascii=False))
+    return 0 if report["passed"] else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/bundled-tools/clis/maggie_docs.py

@@ -1,5 +1,5 @@
 #!/usr/bin/env python3
-"""Audit project documentation for stale trackers and unreferenced files."""
+"""Audit project documentation for stale trackers, unreferenced files, and conflicting rollout status."""
 
 from __future__ import annotations
 
@@ -126,16 +126,94 @@ def audit(project: Path, docs_dir: str = "docs") -> dict:
     }
 
 
+HISTORICAL_RE = re.compile(r"documentation-status:\s*historical-snapshot", re.I)
+ROLLOUT_STATES = ("planned", "in_progress", "blocked", "complete")
+CLAIM_PATTERNS = (
+    ("complete", re.compile(r"(?i)^\s*[-*]\s*\[x\]|\b(?:complete|completed|done|shipped|live|resolved)\b")),
+    ("open", re.compile(r"(?i)^\s*[-*]\s*\[ \]|\b(?:in[ -]progress|pending|ongoing|planned|not started|blocked|todo|unchecked)\b")),
+)
+
+
+def _claim(line: str) -> str | None:
+    """Return complete/open for a status line, or None when absent or ambiguous."""
+    found = {state for state, pattern in CLAIM_PATTERNS if pattern.search(line)}
+    return found.pop() if len(found) == 1 else None
+
+
+def rollout_status(project: Path, docs_dir: str = "docs", status_file: str = "docs/rollout-status.json", id_pattern: str = r"\b[A-Z][A-Z0-9]+-\d+\b") -> dict:
+    """Find documents whose rollout claims disagree with each other or with the canonical status file."""
+    root = project.resolve()
+    docs = (root / docs_dir).resolve()
+    errors: list[str] = []
+    canonical: dict[str, dict] = {}
+    canonical_path = root / status_file
+    if canonical_path.is_file():
+        data = json.loads(canonical_path.read_text(encoding="utf-8"))
+        if data.get("schemaVersion") != "maggie-rollout-status.v1" or not isinstance(data.get("items"), list):
+            errors.append(f"{status_file} must use schemaVersion maggie-rollout-status.v1 with an items list")
+        for item in data.get("items") or []:
+            item_id, state = str(item.get("id") or ""), item.get("status")
+            if not item_id or state not in ROLLOUT_STATES:
+                errors.append(f"{status_file}: item {item_id or '?'} needs an id and a status in {', '.join(ROLLOUT_STATES)}")
+                continue
+            if state == "complete" and not item.get("evidence"):
+                errors.append(f"{status_file}: {item_id} is complete without evidence")
+            canonical[item_id] = item
+    pattern = re.compile(id_pattern)
+    claims: dict[str, list[dict]] = {}
+    historical: list[str] = []
+    for path in _files(docs) if docs.is_dir() else []:
+        if path.suffix.casefold() not in {".md", ".mdx"}:
+            continue
+        text = path.read_text(encoding="utf-8", errors="replace")
+        relative = str(path.relative_to(root))
+        if HISTORICAL_RE.search(text):
+            historical.append(relative)
+            continue
+        for number, line in enumerate(text.splitlines(), 1):
+            ids = set(pattern.findall(line))
+            claim = _claim(line) if len(ids) == 1 else None
+            if claim:
+                claims.setdefault(ids.pop(), []).append({"path": relative, "line": number, "claim": claim})
+    conflicts = []
+    for item_id, found in sorted(claims.items()):
+        if item_id in canonical:
+            expected = "complete" if canonical[item_id]["status"] == "complete" else "open"
+            wrong = [claim for claim in found if claim["claim"] != expected]
+            if wrong:
+                conflicts.append({"id": item_id, "canonical": canonical[item_id]["status"], "claims": wrong})
+        elif len({claim["claim"] for claim in found}) > 1:
+            conflicts.append({"id": item_id, "canonical": None, "claims": found})
+    errors.extend(f"{item['id']}: conflicting rollout status in {', '.join(sorted({c['path'] for c in item['claims']}))}" for item in conflicts)
+    return {
+        "schemaVersion": "maggie-rollout-status-audit.v1",
+        "passed": not errors,
+        "canonical": str(canonical_path.relative_to(root)) if canonical_path.is_file() else None,
+        "itemCount": len(claims),
+        "historicalSnapshots": historical,
+        "conflicts": conflicts,
+        "errors": errors,
+    }
+
+
 def main() -> int:
     parser = argparse.ArgumentParser(description=__doc__)
-    parser.add_argument("audit", nargs="?", choices=("audit",), default="audit")
+    parser.add_argument("command", nargs="?", choices=("audit", "rollout-status"), default="audit")
     parser.add_argument("--project", default=".")
     parser.add_argument("--docs-dir", default="docs")
     parser.add_argument("--fail-on-findings", action="store_true")
+    parser.add_argument("--status-file", default="docs/rollout-status.json", help="canonical maggie-rollout-status.v1 file (rollout-status)")
+    parser.add_argument("--id-pattern", default=r"\b[A-Z][A-Z0-9]+-\d+\b", help="regex for rollout item IDs such as MSG-14 (rollout-status)")
     parser.add_argument("--output")
     args = parser.parse_args()
-    result = audit(Path(args.project), args.docs_dir)
-    if args.fail_on_findings and result.get("findingCount"):
+    if args.command == "rollout-status":
+        try:
+            result = rollout_status(Path(args.project), args.docs_dir, args.status_file, args.id_pattern)
+        except (OSError, ValueError, json.JSONDecodeError, re.error) as error:
+            result = {"schemaVersion": "maggie-rollout-status-audit.v1", "passed": False, "errors": [str(error)]}
+    else:
+        result = audit(Path(args.project), args.docs_dir)
+    if args.command == "audit" and args.fail_on_findings and result.get("findingCount"):
         result["passed"] = False
         result.setdefault("errors", []).append("documentation findings require review")
     if args.output: