@topy-ai/maggie 0.7.13 → 0.7.15

package/bundled-tools/clis/maggie_qa_workflow.py

@@ -0,0 +1,367 @@
+#!/usr/bin/env python3
+"""Track project scenario-based browser QA from test through retest.
+
+The command stores secret-free run state in ``.maggie/qa-runs``. Browser
+interaction remains with the selected browser skill; this CLI records the
+scenario, evidence references, fix event and final release decision.
+"""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import os
+import re
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+from urllib.parse import urlsplit, urlunsplit
+
+
+DEFAULT_SCENARIOS = Path(".maggie") / "scenario-manifest.json"
+VALID_STATUSES = {"pending", "pass", "fail", "blocked", "inconclusive"}
+VALID_PHASES = {"test", "fix", "retest"}
+SECRET_RE = re.compile(
+    r"(?i)(bearer\s+|(?:api[_-]?key|token|secret|password|authorization|cookie)\s*[=:]\s*)[^\s,;]+"
+)
+EMAIL_RE = re.compile(r"\b[\w.+-]+@[\w.-]+\.[A-Za-z]{2,}\b")
+QUERY_SECRET_RE = re.compile(r"(?i)([?&](?:token|key|secret|password|code|id_token|access_token)=)[^&\s]+")
+
+
+def now() -> str:
+    return datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
+
+
+def safe_text(value: object, limit: int = 1200) -> str:
+    text = str(value or "").strip()
+    text = SECRET_RE.sub(r"\1[REDACTED]", text)
+    text = QUERY_SECRET_RE.sub(r"\1[REDACTED]", text)
+    text = EMAIL_RE.sub("[REDACTED_EMAIL]", text)
+    return text[:limit]
+
+
+def safe_base_url(value: object) -> str:
+    """Keep the origin only so reports do not retain private paths or queries."""
+    text = safe_text(value, 500)
+    try:
+        parsed = urlsplit(text)
+        if parsed.scheme and parsed.hostname:
+            netloc = parsed.hostname
+            if parsed.port:
+                netloc = f"{netloc}:{parsed.port}"
+            return urlunsplit((parsed.scheme, netloc, "", "", ""))
+    except ValueError:
+        pass
+    return text
+
+
+def project_root(value: str | os.PathLike[str]) -> Path:
+    return Path(value).expanduser().resolve()
+
+
+def load_json(path: Path) -> dict:
+    try:
+        value = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as error:
+        raise ValueError(f"could not read JSON {path}: {error}") from error
+    if not isinstance(value, dict):
+        raise ValueError(f"JSON root must be an object: {path}")
+    return value
+
+
+def scenario_records(path: Path) -> list[dict]:
+    manifest = load_json(path)
+    scenarios = manifest.get("scenarios")
+    if not isinstance(scenarios, list) or not scenarios:
+        raise ValueError("scenario manifest must contain a non-empty scenarios array")
+    result = []
+    seen: set[str] = set()
+    for item in scenarios:
+        if not isinstance(item, dict) or not isinstance(item.get("id"), str):
+            raise ValueError("each scenario must be an object with an id")
+        scenario_id = item["id"]
+        if scenario_id in seen:
+            raise ValueError(f"duplicate scenario id: {scenario_id}")
+        seen.add(scenario_id)
+        result.append(item)
+    return result
+
+
+def run_directory(project: Path) -> Path:
+    directory = project / ".maggie" / "qa-runs"
+    directory.mkdir(parents=True, exist_ok=True)
+    return directory
+
+
+def normal_run_id(value: str | None) -> str:
+    if value:
+        value = re.sub(r"[^A-Za-z0-9._-]+", "-", value).strip("-")
+        if not value:
+            raise ValueError("run id cannot be empty")
+        return value
+    return "qa-" + datetime.now(timezone.utc).strftime("%Y%m%d-%H%M%S")
+
+
+def run_path(project: Path, value: str) -> Path:
+    candidate = Path(value).expanduser()
+    if candidate.suffix == ".json" or candidate.parent != Path("."):
+        path = candidate if candidate.is_absolute() else project / candidate
+    else:
+        path = run_directory(project) / f"{normal_run_id(value)}.json"
+    path = path.resolve()
+    if not path.is_file():
+        raise ValueError(f"QA run does not exist: {path}")
+    return path
+
+
+def write_json(path: Path, value: dict) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    temporary = path.with_suffix(path.suffix + ".tmp")
+    temporary.write_text(json.dumps(value, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+    temporary.replace(path)
+
+
+def calculate(run: dict) -> dict:
+    counts = {status: 0 for status in VALID_STATUSES}
+    lifecycle_counts = {"ready": 0, "fix_pending": 0}
+    for item in run.get("scenarios", {}).values():
+        status = item.get("status", "pending")
+        counts[status] = counts.get(status, 0) + 1
+        lifecycle_counts["fix_pending" if item.get("lifecycle") == "fix_pending" else "ready"] += 1
+    if counts["fail"]:
+        gate = "fail"
+    elif counts["pending"] or counts["blocked"] or counts["inconclusive"]:
+        gate = "blocked"
+    else:
+        gate = "pass"
+    return {"gate": gate, "counts": counts, "lifecycle": lifecycle_counts, "total": sum(counts.values())}
+
+
+def start(args: argparse.Namespace) -> int:
+    project = project_root(args.project)
+    manifest_path = project_root(args.scenario_file) if Path(args.scenario_file).is_absolute() else project / args.scenario_file
+    records = scenario_records(manifest_path)
+    run_id = normal_run_id(args.run_id)
+    path = run_directory(project) / f"{run_id}.json"
+    if path.exists():
+        raise ValueError(f"QA run already exists: {path}")
+    scenarios = {
+        item["id"]: {
+            "id": item["id"],
+            "group": item.get("group", ""),
+            "title": item.get("title", ""),
+            "priority": item.get("priority", "P2"),
+            "routes": item.get("routes", []),
+            "auth": item.get("auth", ""),
+            "browser": bool(item.get("browser", True)),
+            "status": "pending",
+            "lifecycle": "ready",
+            "history": [],
+        }
+        for item in records
+    }
+    try:
+        manifest_label = str(manifest_path.relative_to(project))
+    except ValueError:
+        # Do not persist an absolute path outside the project. The basename is
+        # enough to identify the source without leaking a local filesystem
+        # layout into a shareable run artifact.
+        manifest_label = manifest_path.name
+    run = {
+        "schemaVersion": "maggie.qa-run.v1",
+        "runId": run_id,
+        "createdAt": now(),
+        "updatedAt": now(),
+        "project": hashlib.sha256(str(project).encode()).hexdigest()[:16],
+        "environment": safe_text(args.environment),
+        "baseUrl": safe_base_url(args.base_url),
+        "browser": safe_text(args.browser),
+        "commit": safe_text(args.commit),
+        "release": safe_text(args.release),
+        "scenarioManifest": manifest_label,
+        "scenarios": scenarios,
+    }
+    run["summary"] = calculate(run)
+    write_json(path, run)
+    print(json.dumps({"runId": run_id, "path": str(path), "summary": run["summary"]}, ensure_ascii=False, indent=2))
+    return 0
+
+
+def evidence(value: str, project: Path) -> dict:
+    clean = safe_text(value, 500)
+    path = Path(value).expanduser()
+    if path.is_file():
+        resolved = path.resolve()
+        try:
+            display = str(resolved.relative_to(project))
+        except ValueError:
+            display = resolved.name
+        return {"path": display, "sha256": hashlib.sha256(resolved.read_bytes()).hexdigest()}
+    return {"reference": clean}
+
+
+def record(args: argparse.Namespace) -> int:
+    project = project_root(args.project)
+    path = run_path(project, args.run)
+    run = load_json(path)
+    scenarios = run.get("scenarios", {})
+    item = scenarios.get(args.scenario)
+    if not isinstance(item, dict):
+        raise ValueError(f"scenario is not in this run: {args.scenario}")
+    phase = args.phase
+    if phase not in VALID_PHASES:
+        raise ValueError(f"phase must be one of: {', '.join(sorted(VALID_PHASES))}")
+    if phase in {"test", "retest"} and args.status not in VALID_STATUSES - {"pending"}:
+        raise ValueError("test and retest require status pass, fail, blocked or inconclusive")
+    if phase == "fix" and not args.resolution:
+        raise ValueError("fix requires --resolution")
+    if phase == "fix" and item.get("status") != "fail":
+        raise ValueError("fix can only follow a recorded fail; use retest after a blocked or inconclusive run")
+    if phase == "retest" and not any(event.get("phase") == "test" for event in item.get("history", [])):
+        raise ValueError("retest requires an earlier test event")
+    if phase == "retest" and item.get("status") == "fail" and not any(event.get("phase") == "fix" for event in item.get("history", [])):
+        raise ValueError("a failed scenario must have a recorded fix before retest")
+    if phase == "test" and args.status == "fail" and not (args.expected and args.actual and args.error_fingerprint):
+        raise ValueError("a failed test requires --expected, --actual and --error-fingerprint")
+    event = {
+        "at": now(),
+        "phase": phase,
+        "status": args.status if phase != "fix" else "fix_pending",
+        "summary": safe_text(args.summary),
+        "expected": safe_text(args.expected),
+        "actual": safe_text(args.actual),
+        "errorFingerprint": safe_text(args.error_fingerprint, 300),
+        "issue": safe_text(args.issue, 500),
+        "resolution": safe_text(args.resolution),
+        "validation": safe_text(args.validation),
+        "evidence": [evidence(value, project) for value in args.evidence],
+    }
+    item.setdefault("history", []).append(event)
+    if phase == "fix":
+        item["lifecycle"] = "fix_pending"
+    else:
+        item["status"] = args.status
+        item["lifecycle"] = "ready"
+    run["updatedAt"] = now()
+    run["summary"] = calculate(run)
+    write_json(path, run)
+    print(json.dumps({"runId": run.get("runId"), "scenario": args.scenario, "event": event, "summary": run["summary"]}, ensure_ascii=False, indent=2))
+    return 0
+
+
+def markdown(run: dict) -> str:
+    summary = run.get("summary") or calculate(run)
+    lines = [
+        f"# Maggie QA run `{run.get('runId', '')}`",
+        "",
+        "<!-- Generated by maggie_qa_workflow.py. Evidence is metadata-only. -->",
+        "",
+        f"- Environment: `{run.get('environment') or 'not provided'}`",
+        f"- Base URL: `{run.get('baseUrl') or 'not provided'}`",
+        f"- Browser: `{run.get('browser') or 'not provided'}`",
+        f"- Commit/release: `{run.get('commit') or 'not provided'}` / `{run.get('release') or 'not provided'}`",
+        f"- Gate: **{summary.get('gate', 'blocked').upper()}**",
+        "",
+        "## Scenario summary",
+        "",
+        "| ID | Priority | Scenario | Status | Lifecycle | Last result |",
+        "|---|---|---|---|---|---|",
+    ]
+    for scenario in run.get("scenarios", {}).values():
+        history = scenario.get("history", [])
+        last = history[-1] if history else {}
+        result = safe_text(last.get("summary") or last.get("actual") or "Not tested", 180).replace("|", "\\|")
+        lines.append(f"| {scenario.get('id')} | {scenario.get('priority')} | {scenario.get('title')} | **{scenario.get('status')}** | {scenario.get('lifecycle')} | {result} |")
+    lines += ["", "## Fix and retest history", ""]
+    for scenario in run.get("scenarios", {}).values():
+        for event in scenario.get("history", []):
+            lines.append(f"### {scenario.get('id')} — {event.get('phase')} ({event.get('at')})")
+            lines.append("")
+            if event.get("summary"): lines.append(f"- Summary: {event['summary']}")
+            if event.get("expected"): lines.append(f"- Expected: {event['expected']}")
+            if event.get("actual"): lines.append(f"- Actual: {event['actual']}")
+            if event.get("errorFingerprint"): lines.append(f"- Error fingerprint: `{event['errorFingerprint']}`")
+            if event.get("resolution"): lines.append(f"- Resolution: {event['resolution']}")
+            if event.get("validation"): lines.append(f"- Validation: {event['validation']}")
+            references = event.get("evidence", [])
+            if references: lines.append(f"- Evidence: {', '.join(str(value.get('path') or value.get('reference')) for value in references)}")
+            lines.append("")
+    return "\n".join(lines).rstrip() + "\n"
+
+
+def summary(args: argparse.Namespace) -> int:
+    project = project_root(args.project)
+    run = load_json(run_path(project, args.run))
+    result = run.get("summary") or calculate(run)
+    if args.format == "markdown":
+        print(markdown(run))
+    else:
+        print(json.dumps({"runId": run.get("runId"), **result}, ensure_ascii=False, indent=2))
+    return 0 if result.get("gate") == "pass" else 1
+
+
+def export_run(args: argparse.Namespace) -> int:
+    project = project_root(args.project)
+    run = load_json(run_path(project, args.run))
+    output = Path(args.output).expanduser()
+    if not output.is_absolute(): output = project / output
+    output.parent.mkdir(parents=True, exist_ok=True)
+    output.write_text(markdown(run), encoding="utf-8")
+    print(json.dumps({"runId": run.get("runId"), "output": str(output.resolve()), "gate": run.get("summary", {}).get("gate")}, ensure_ascii=False, indent=2))
+    return 0
+
+
+def parser() -> argparse.ArgumentParser:
+    root = argparse.ArgumentParser(description=__doc__)
+    root.add_argument("--project", default=".")
+    commands = root.add_subparsers(dest="command", required=True)
+
+    start_parser = commands.add_parser("start")
+    start_parser.add_argument("--project", default=argparse.SUPPRESS)
+    start_parser.add_argument("--scenario-file", default=str(DEFAULT_SCENARIOS))
+    start_parser.add_argument("--run-id")
+    start_parser.add_argument("--environment", required=True)
+    start_parser.add_argument("--base-url", required=True)
+    start_parser.add_argument("--browser", default="chrome")
+    start_parser.add_argument("--commit", default="")
+    start_parser.add_argument("--release", default="")
+
+    record_parser = commands.add_parser("record")
+    record_parser.add_argument("--project", default=argparse.SUPPRESS)
+    record_parser.add_argument("--run", required=True)
+    record_parser.add_argument("--scenario", required=True)
+    record_parser.add_argument("--phase", choices=sorted(VALID_PHASES), required=True)
+    record_parser.add_argument("--status", choices=sorted(VALID_STATUSES - {"pending"}))
+    record_parser.add_argument("--summary", default="")
+    record_parser.add_argument("--expected", default="")
+    record_parser.add_argument("--actual", default="")
+    record_parser.add_argument("--error-fingerprint", default="")
+    record_parser.add_argument("--issue", default="")
+    record_parser.add_argument("--resolution", default="")
+    record_parser.add_argument("--validation", default="")
+    record_parser.add_argument("--evidence", action="append", default=[])
+
+    for name in ("summary", "export"):
+        command = commands.add_parser(name)
+        command.add_argument("--project", default=argparse.SUPPRESS)
+        command.add_argument("--run", required=True)
+        if name == "summary": command.add_argument("--format", choices=("json", "markdown"), default="json")
+        else: command.add_argument("--output", required=True)
+    return root
+
+
+def main() -> int:
+    args = parser().parse_args()
+    try:
+        if args.command == "start": return start(args)
+        if args.command == "record": return record(args)
+        if args.command == "summary": return summary(args)
+        return export_run(args)
+    except (OSError, ValueError, json.JSONDecodeError) as error:
+        print(f"QA workflow error: {safe_text(error)}", file=sys.stderr)
+        return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/bundled-tools/runtime/maggie_api_contract.py

@@ -0,0 +1,97 @@
+"""Provider-neutral request/response contract checks for HTTP APIs."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+
+
+SCHEMA = "maggie-api-contract.v1"
+METHODS = {"get", "post", "put", "patch", "delete", "head", "options", "trace"}
+BODY_METHODS = {"post", "put", "patch"}
+
+
+def _has_schema(value: object) -> bool:
+    if not isinstance(value, Mapping):
+        return False
+    if "$ref" in value:
+        return bool(str(value["$ref"]).strip())
+    schema = value.get("schema")
+    if isinstance(schema, Mapping):
+        return _has_schema(schema) or bool(schema)
+    content = value.get("content")
+    if isinstance(content, Mapping):
+        return any(_has_schema(media) for media in content.values())
+    return False
+
+
+def _success_responses(responses: Mapping[str, Any]) -> list[tuple[str, Mapping[str, Any]]]:
+    result = []
+    for code, response in responses.items():
+        label = str(code).upper()
+        if label.startswith("2") or label == "2XX":
+            result.append((str(code), response if isinstance(response, Mapping) else {}))
+    return result
+
+
+def validate_api_contract(spec: object) -> dict[str, Any]:
+    """Validate declared body and success response shapes without guessing fields.
+
+    Empty request/response bodies are valid only when they are explicit (or a
+    204 response). This keeps a consumer from inventing fields for an
+    under-specified endpoint while allowing intentional command-style APIs.
+    """
+    errors: list[dict[str, str]] = []
+    operations: list[dict[str, Any]] = []
+    paths = spec.get("paths") if isinstance(spec, Mapping) else None
+    if not isinstance(paths, Mapping):
+        return {"schemaVersion": SCHEMA, "passed": False, "operations": [],
+                "errors": [{"code": "paths-missing", "message": "spec.paths must be an object"}]}
+    for path, path_item in sorted(paths.items(), key=lambda item: str(item[0])):
+        if not isinstance(path_item, Mapping):
+            errors.append({"path": str(path), "code": "path-invalid", "message": "path item must be an object"})
+            continue
+        for method, operation in sorted(path_item.items(), key=lambda item: str(item[0])):
+            verb = str(method).casefold()
+            if verb not in METHODS:
+                continue
+            operation_id = str((operation or {}).get("operationId") or f"{verb} {path}") if isinstance(operation, Mapping) else f"{verb} {path}"
+            record: dict[str, Any] = {"path": str(path), "method": verb.upper(), "operationId": operation_id}
+            if not isinstance(operation, Mapping):
+                errors.append({"path": str(path), "method": verb.upper(), "code": "operation-invalid", "message": "operation must be an object"})
+                continue
+            if verb in BODY_METHODS:
+                body = operation.get("requestBody")
+                if body is None and not operation.get("x-maggie-empty-request-body"):
+                    errors.append({"path": str(path), "method": verb.upper(), "code": "request-body-undeclared", "message": "declare requestBody or x-maggie-empty-request-body"})
+                    record["requestBody"] = "missing"
+                elif operation.get("x-maggie-empty-request-body"):
+                    record["requestBody"] = "explicit-empty"
+                elif not _has_schema(body):
+                    errors.append({"path": str(path), "method": verb.upper(), "code": "request-body-schema-missing", "message": "requestBody must declare content.schema or $ref"})
+                    record["requestBody"] = "schema-missing"
+                else:
+                    record["requestBody"] = "declared"
+            else:
+                record["requestBody"] = "not-applicable"
+            responses = operation.get("responses")
+            if not isinstance(responses, Mapping):
+                errors.append({"path": str(path), "method": verb.upper(), "code": "responses-missing", "message": "declare responses with a 2xx success response"})
+                record["successResponse"] = "missing"
+            else:
+                successes = _success_responses(responses)
+                if not successes:
+                    errors.append({"path": str(path), "method": verb.upper(), "code": "success-response-missing", "message": "declare at least one 2xx response"})
+                    record["successResponse"] = "missing"
+                else:
+                    code, response = successes[0]
+                    if code == "204" or response.get("x-maggie-empty-response"):
+                        record["successResponse"] = f"{code}:explicit-empty"
+                    elif not _has_schema(response):
+                        errors.append({"path": str(path), "method": verb.upper(), "code": "success-response-schema-missing", "message": f"response {code} must declare content.schema, $ref, or x-maggie-empty-response"})
+                        record["successResponse"] = f"{code}:schema-missing"
+                    else:
+                        record["successResponse"] = f"{code}:declared"
+            operations.append(record)
+    return {"schemaVersion": SCHEMA, "passed": not errors, "operations": operations, "errors": errors,
+            "operationCount": len(operations), "errorCount": len(errors)}

package/bundled-tools/runtime/maggie_blog.py

@@ -18,6 +18,8 @@ DEFAULTS = {
     "postsPerPage": 9,
     "topicLimit": 12,
     "defaultPostStatus": "draft",
+    "requireReview": True,
+    "autoPublishEnabled": False,
     "autoPullEnabled": False,
     "pullIntervalMinutes": 120,
     "maxPerRun": 1,
@@ -142,6 +144,12 @@ class BlogStore:
             if not content_id or not title: raise ValueError("each post requires contentId/id and title")
             old = by_content.get(content_id)
             raw_slug = str(item.get("slug") or title)
+            initial_status = settings.get("defaultPostStatus", "draft")
+            # A provider must not turn an import into an implicit publication.
+            # Older projects may still carry defaultPostStatus=published; the
+            # review gate makes that configuration visible and safe here.
+            if settings.get("requireReview", True) and initial_status != "draft":
+                initial_status = "draft"
             post = {
                 "schemaVersion": "maggie-blog-post.v1",
                 "id": old["id"] if old else f"post:{content_id}",
@@ -156,7 +164,7 @@ class BlogStore:
                 "topics": [{"slug": slugify(str(topic)), "label": str(topic)} for topic in item.get("topics", item.get("keywords", []))],
                 # Provider input can suggest a status, but cannot bypass the
                 # local approval gate. Existing published state is preserved.
-                "status": old.get("status", settings["defaultPostStatus"]) if old else settings["defaultPostStatus"],
+                "status": old.get("status", initial_status) if old else initial_status,
                 "canonicalUrl": item.get("canonicalUrl"),
                 "source": {"provider": provider, "revision": str(item.get("revision") or checksum(item))},
                 "publishedAt": old.get("publishedAt") if old else item.get("publishedAt"),
@@ -183,6 +191,8 @@ class BlogStore:
 
     def validate(self) -> dict:
         settings = self.settings(); posts = self.posts(); errors = []
+        gate = self.review_gate(settings)
+        errors.extend(f"review gate: {error}" for error in gate["errors"])
         ids = [p.get("contentId") for p in posts]; slugs = [p.get("slug") for p in posts]
         if len(ids) != len(set(ids)): errors.append("duplicate contentId")
         if len(slugs) != len(set(slugs)): errors.append("duplicate slug")
@@ -192,11 +202,42 @@ class BlogStore:
             if post.get("status") == "published" and not post.get("publishedAt"): errors.append(f"{post.get('id')}: publishedAt required")
         return {"valid": not errors, "posts": len(posts), "published": sum(p.get("status") == "published" for p in posts), "settings": settings, "errors": errors}
 
+    @staticmethod
+    def review_gate(settings: dict) -> dict:
+        """Report whether generated content is forced through human review."""
+        errors: list[str] = []
+        require_review = bool(settings.get("requireReview", True))
+        auto_publish = bool(settings.get("autoPublishEnabled", False))
+        default_status = str(settings.get("defaultPostStatus", "draft"))
+        if auto_publish:
+            errors.append("autoPublishEnabled must be false for provider-neutral draft-first publishing")
+        if not require_review:
+            errors.append("requireReview must be true")
+        if default_status == "published":
+            errors.append("defaultPostStatus cannot be published")
+        return {"schemaVersion": "maggie-blog-review-gate.v1", "passed": not errors,
+                "requireReview": require_review, "autoPublishEnabled": auto_publish,
+                "defaultPostStatus": default_status, "errors": errors,
+                "mutation": False}
+
+    def approve(self, slug: str, actor: str, reason: str) -> dict:
+        if not actor or not reason:
+            raise ValueError("actor and reason are required")
+        posts = self.posts(); found = next((p for p in posts if p.get("slug") == slug), None)
+        if not found: raise ValueError(f"post not found: {slug}")
+        if found["status"] not in {"draft", "review"}:
+            raise ValueError(f"post cannot approve from {found['status']}")
+        found["status"] = "approved"; found["updatedAt"] = now()
+        found["lastTransition"] = {"actor": actor, "reason": reason, "at": now()}
+        self._backup(); self._write(self.posts_path, posts); return found
+
     def publish(self, slug: str, actor: str, reason: str) -> dict:
         if not actor or not reason: raise ValueError("actor and reason are required")
         posts = self.posts(); found = next((p for p in posts if p.get("slug") == slug), None)
         if not found: raise ValueError(f"post not found: {slug}")
         if found["status"] not in {"draft", "review", "approved"}: raise ValueError(f"post cannot publish from {found['status']}")
+        if self.settings().get("requireReview", True) and found["status"] != "approved":
+            raise ValueError("post requires explicit approval before publish")
         found["status"] = "published"; found["publishedAt"] = found.get("publishedAt") or now(); found["updatedAt"] = now(); found["lastTransition"] = {"actor": actor, "reason": reason, "at": now()}
         self._backup(); self._write(self.posts_path, posts); return found