@topy-ai/maggie 0.7.19 → 0.7.21

package/README.md

@@ -192,6 +192,7 @@ maggie seo social-cards ...       # per-page og:image format/dimension audit
 maggie seo head-tags ...          # rendered-shell head metadata drift audit
 maggie ops favicon-check ...      # served favicon behaviour check
 maggie deployment | migration | release | analytics | schedule
+maggie deployment readiness --project PATH
 maggie migration identity --identity-file FILE [--expected-file FILE]
 maggie deployment canary --asset URL=SHA256 --render-report report.json
 maggie design icon-inventory --source-dir src --runtime assets/icons.css
@@ -280,6 +281,25 @@ The canary report requires a screenshot and zero console errors, missing
 assets, and visual placeholders for every route. It records safe cache headers
 only and never stores response bodies, cookies, or credentials.
 
+Unit regression does not establish runtime release readiness. Produce unit
+evidence and then validate all five release evidence slots:
+
+```bash
+python3 tools/tests/run_regression.py \
+  --report .maggie/verification/unit-regression.json
+maggie deployment readiness --project . \
+  --package-report .maggie/verification/package-smoke.json \
+  --browser-report .maggie/verification/browser-evidence.json \
+  --rendered-canary .maggie/deployment-canary.json \
+  --deployment-preflight .maggie/release-preflight.json \
+  --output .maggie/deployment-readiness.json
+```
+
+The readiness report follows `maggie-deployment-readiness.v1`. It reports unit
+regression, package smoke, host browser evidence, rendered canary, and
+deployment preflight separately. Missing host adapter evidence is
+`inconclusive`; only five passing slots produce `passed`.
+
 ### Localization and analytics release gates
 
 Extract real page strings before creating a localization job, then require a
@@ -305,8 +325,8 @@ artifact schemas.
 Recommended upgrade sequence for the current release:
 
 ```bash
-npx @topy-ai/maggie@0.7.19 update --project . --force
-npx @topy-ai/maggie@0.7.19 cleanup --project .
+npx @topy-ai/maggie@0.7.21 update --project . --force
+npx @topy-ai/maggie@0.7.21 cleanup --project .
 ```
 
 Maintainers should pass npm credentials through the repository helper, never
@@ -316,7 +336,11 @@ as a command-line argument:
 node scripts/publish-npm.mjs --maggie-env-file ../.env
 ```
 
-The 0.7.19 workflow adds documentation hygiene audits, live URL API contract
+The 0.7.21 workflow adds operation-specific localization quality checks,
+explicit deployment readiness evidence states, and serialized package assembly.
+The 0.7.20 workflow completes the MaggieDash Activity and Navigation
+workspaces and dashboard UI v3 contract. The 0.7.19 workflow adds
+documentation hygiene audits, live URL API contract
 validation, host-supplied schema reader audits, dashboard runtime evidence,
 and provider-neutral activity-log and managed-navigation contracts. The 0.7.18
 workflow adds staged/untracked changed-surface detection, scenario

package/README.zh-TW.md

@@ -8,7 +8,7 @@ Codex、Claude Code 與相容的 coding agents。
 ## 安裝
 
 ```bash
-npx @topy-ai/maggie@0.7.19 init --agent all
+npx @topy-ai/maggie@0.7.21 init --agent all
 npx @topy-ai/maggie doctor --project .
 ```
 
@@ -25,7 +25,10 @@ maggie doctor --project . --require-bootstrap --strict
 deployment、memory、feedback 和 MaggieDash。內容先 draft/review，外部寫入、
 publish 與 production deployment 需要明確確認。
 
-0.7.19 加入文件 hygiene audit、live URL API contract、schema reader audit、
+0.7.21 增加 localization polish/rewrite 的 operation-specific quality checks、
+deployment readiness evidence 狀態，以及並發 package assembly 保護。
+0.7.20 完成 MaggieDash Activity 與 Navigation workspace，以及 dashboard UI v3
+contract。0.7.19 加入文件 hygiene audit、live URL API contract、schema reader audit、
 dashboard runtime evidence，以及 activity-log 和 managed-navigation contracts。
 0.7.18 加入 staged/untracked changed-surface release gate、QA run 與 release
 整合、market/locale-aware service variant route、provider capability matrix
@@ -37,6 +40,10 @@ MaggieDash 也提供穩定 section identity、可重用 section arrangement、
 section registry、短期 agent content bridge，以及 translation out-of-band write
 後的 restart gate。`maggie doctor` 會比較 install manifest 與磁碟上的實際 skills。
 
+`maggie deployment readiness` 會分開檢查 unit regression、package smoke、host
+browser evidence、rendered canary 與 deployment preflight。缺少必要 adapter 時
+回傳 `inconclusive`，只有五組 evidence 全部通過才回傳 `passed`。
+
 新版 release gates：
 
 ```bash

package/bin/maggie.js

@@ -108,6 +108,7 @@ Usage:
   maggie service convert-page <page-path> --project PATH
   maggie service match-pages --project PATH --pages-dir src/pages
   maggie deployment --project PATH --target vps-with-cloudflare-dns
+  maggie deployment readiness --project PATH
   maggie deployment canary --project PATH --asset URL=SHA256 --render-report report.json --output docs/deployment-canary.json
   maggie migration --project PATH --environment staging
   maggie migration identity --identity-file FILE [--expected-file FILE]
@@ -408,6 +409,7 @@ try {
   else if (command === "seo") seo(args);
   else if (command === "ops") workflowCli("maggie_ops.py", args);
   else if (command === "deployment" && args[0] === "canary") workflowCli("maggie_deployment_canary.py", args.slice(1));
+  else if (command === "deployment" && args[0] === "readiness") workflowCli("maggie_deployment_readiness.py", args.slice(1));
   else if (command === "deployment") workflowCli("maggie_deployment.py", args);
   else if (command === "migration") workflowCli("maggie_migration.py", args);
   else if (command === "schedule") workflowCli("maggie_schedule.py", args);

package/bundled-contracts/maggie-deployment/readiness-v1.schema.json

@@ -0,0 +1,37 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://maggie.noblox.app/contracts/deployment-readiness-v1.json",
+  "title": "Maggie deployment readiness evidence summary",
+  "type": "object",
+  "required": ["schemaVersion", "status", "checks"],
+  "properties": {
+    "schemaVersion": {"const": "maggie-deployment-readiness.v1"},
+    "status": {"enum": ["passed", "failed", "inconclusive"]},
+    "checks": {
+      "type": "object",
+      "required": ["unitRegression", "packageSmoke", "browserEvidence", "renderedCanary", "deploymentPreflight"],
+      "additionalProperties": false,
+      "properties": {
+        "unitRegression": {"$ref": "#/$defs/check"},
+        "packageSmoke": {"$ref": "#/$defs/check"},
+        "browserEvidence": {"$ref": "#/$defs/check"},
+        "renderedCanary": {"$ref": "#/$defs/check"},
+        "deploymentPreflight": {"$ref": "#/$defs/check"}
+      }
+    }
+  },
+  "$defs": {
+    "check": {
+      "type": "object",
+      "required": ["state", "configured"],
+      "properties": {
+        "state": {"enum": ["passed", "failed", "inconclusive", "not-configured"]},
+        "configured": {"type": "boolean"},
+        "path": {"type": "string"},
+        "reason": {"type": "string"}
+      },
+      "additionalProperties": true
+    }
+  },
+  "additionalProperties": false
+}

package/bundled-contracts/maggiedash/README.md

@@ -61,6 +61,12 @@ Dashboard browser checks must emit runtime evidence; a static component scan
 or JSON declaration is not proof that a screen mounted or that its data calls
 ran.
 
+The first-party MaggieDash 0.2.4 distribution exposes these adapters through
+its dashboard UI v3 contract: a read-only Activity workspace and an atomic,
+locale-aware Navigation workspace. The reusable UI accepts the standard
+`events`/`occurredAt` and `items`/`destination` shapes, while also reading the
+legacy host response aliases used by existing adapters during migration.
+
 ## Status model
 
 Content transitions are explicit:

package/bundled-references/content-localization-contract.md

@@ -61,6 +61,15 @@ Supported operations are distinct: `translate`, `polish`, `rewrite`,
 source. A source revision change marks dependent translations stale. Fallback
 content is never indexable.
 
+`polish` and `rewrite` validation includes deterministic output checks. Polish
+must keep the source language, change the copy, preserve protected fact tokens,
+and show a clarity signal (shorter maximum sentence, clearer sentence
+segmentation, placeholder reduction, or explicit quality evidence). Rewrite
+must change the copy and its observable structure, while preserving protected
+fact tokens. These are conservative heuristics, not semantic equivalence
+proof: every result contains `quality.humanReview.required: true` and marks
+semantic equivalence as `not-certified` until a named reviewer approves it.
+
 The following are protected by default: price, currency, rating, provider
 facts, booking URL, legal/health claims, content ID, slug, canonical owner,
 and translation group. Changes require structured approval and evidence.

package/bundled-skills/maggie-content-localization/SKILL.md

@@ -14,9 +14,12 @@ metadata:
 changes; translate and polish preserve meaning; localise enables market
 adaptation. A host generation adapter or the authoring agent must apply these
 instructions when producing copy. Planning does not invoke a model or generate
-translations. Validation currently checks mode consistency and rewrite
-permission, not whether prose was actually restructured. Review the produced
-copy against the requested operation before approval.
+translations. Validation now applies deterministic operation-specific checks to
+polish and rewrite outputs: source/output text must be present, protected fact
+tokens must remain unchanged, polish must show a clarity signal, and rewrite
+must change observable structure. These checks are conservative heuristics,
+not semantic equivalence proof. Every result requires named human review and
+reports `semanticEquivalence: not-certified` until approval.
 
 ### Resumable draft generation
 

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

@@ -46,6 +46,15 @@ owns the framework route, email/password session middleware, database, media
 storage, provider credentials, and `/api/maggie/*` adapter endpoints. Read the
 MaggieDash host adapter contract before adding a new framework adapter.
 
+MaggieDash 0.2.4 adds two reusable operator workspaces. Activity is a read-only
+view backed by `/api/maggie/activity.json`; it supports actor/action filters,
+refresh, and a safe unavailable state. Navigation is an ordered,
+locale/location-aware editor backed by `/api/maggie/navigation.json`; it saves
+the full menu atomically and requires the host to keep published markup as its
+fallback. The host owns authentication, event writes, menu persistence,
+translation behavior, and validation. Use the dashboard UI v3 contract for the
+required route and capability declarations.
+
 For a built/deployed host, an agent must use the host's validated content
 bridge rather than editing release files or receiving database credentials:
 

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

@@ -37,6 +37,31 @@ visitor-facing files. The canary must include screenshots, zero console or
 network errors, and zero placeholder matches. Query-driven routes belong in
 behavior/API checks, not static byte baselines.
 
+## Release readiness evidence
+
+Unit regression is necessary but does not prove runtime release readiness. The
+readiness command keeps five evidence slots separate: dependency-free unit
+regression, package smoke, host browser evidence, rendered canary, and
+deployment preflight:
+
+```bash
+python3 tools/tests/run_regression.py \
+  --report .maggie/verification/unit-regression.json
+maggie deployment readiness --project . \
+  --package-report .maggie/verification/package-smoke.json \
+  --browser-report .maggie/verification/browser-evidence.json \
+  --rendered-canary .maggie/deployment-canary.json \
+  --deployment-preflight .maggie/release-preflight.json \
+  --output .maggie/deployment-readiness.json
+```
+
+The report follows `maggie-deployment-readiness.v1`. A failed evidence file
+returns `failed`; a missing or unavailable host/browser adapter returns
+`inconclusive`; only five passing evidence slots return `passed`. Maggie does
+not fabricate browser, rendered, or deployment evidence and does not deploy
+from this command. See
+[`readiness-v1.schema.json`](../../bundled-contracts/maggie-deployment/readiness-v1.schema.json).
+
 ## Automatic memory hook
 
 Follow [Maggie Memory Hook](../../references/memory-hook.md) at invocation and completion.

package/bundled-tools/clis/maggie_deployment_readiness.py

@@ -0,0 +1,158 @@
+#!/usr/bin/env python3
+"""Summarize release evidence without confusing tests with runtime readiness."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Callable
+
+
+CHECKS = (
+    ("unitRegression", "unit_report"),
+    ("packageSmoke", "package_report"),
+    ("browserEvidence", "browser_report"),
+    ("renderedCanary", "rendered_canary"),
+    ("deploymentPreflight", "deployment_preflight"),
+)
+
+
+def display_path(path: Path, project: Path) -> str:
+    try:
+        return str(path.resolve().relative_to(project.resolve()))
+    except ValueError:
+        return path.name
+
+
+def validate_unit(payload: dict[str, Any]) -> tuple[bool, str]:
+    if payload.get("schemaVersion") != "maggie-regression.v1":
+        return False, "unit evidence schemaVersion is unsupported"
+    if payload.get("status") != "passed" or not isinstance(payload.get("suites"), int) or payload["suites"] < 1:
+        return False, "unit evidence must report a passing suite count"
+    if payload.get("skipped", 0) != 0:
+        return False, "unit evidence contains skipped suites"
+    return True, "dependency-free regression suites passed"
+
+
+def validate_package(payload: dict[str, Any]) -> tuple[bool, str]:
+    if payload.get("schemaVersion") != "maggie-package-smoke.v1":
+        return False, "package evidence schemaVersion is unsupported"
+    checks = payload.get("checks")
+    if payload.get("passed") is not True or not isinstance(checks, list) or not checks:
+        return False, "package evidence must contain passing smoke checks"
+    return True, "package smoke checks passed"
+
+
+def validate_browser(payload: dict[str, Any]) -> tuple[bool, str]:
+    if payload.get("schemaVersion") != "maggie-browser-evidence.v1":
+        return False, "browser evidence schemaVersion is unsupported"
+    routes = payload.get("routes")
+    if payload.get("passed") is not True or not isinstance(routes, list) or not routes:
+        return False, "browser evidence must contain a passing non-empty route set"
+    for route in routes:
+        if not isinstance(route, dict) or not route.get("route") or not route.get("screenshot"):
+            return False, "browser evidence routes need a route and screenshot"
+        if route.get("consoleErrors") or route.get("networkErrors") or route.get("missingAssets"):
+            return False, "browser evidence contains runtime errors"
+    return True, "host browser evidence passed"
+
+
+def validate_canary(payload: dict[str, Any]) -> tuple[bool, str]:
+    if payload.get("schemaVersion") != "maggie-deployment-canary.v1":
+        return False, "rendered canary schemaVersion is unsupported"
+    if payload.get("status") != "pass":
+        return False, "rendered canary did not pass"
+    rendered = payload.get("rendered")
+    if not isinstance(rendered, dict) or not isinstance(rendered.get("report"), dict):
+        return False, "rendered canary is missing browser-rendered report evidence"
+    return True, "edge and rendered canary passed"
+
+
+def validate_preflight(payload: dict[str, Any]) -> tuple[bool, str]:
+    if payload.get("schemaVersion") not in {"1.0", "maggie-release-preflight.v1"}:
+        return False, "deployment preflight schemaVersion is unsupported"
+    if payload.get("passed") is not True:
+        return False, "deployment preflight contains a failed gate"
+    gates = payload.get("gates")
+    if not isinstance(gates, list) or not gates:
+        return False, "deployment preflight has no gate results"
+    return True, "deployment preflight gates passed"
+
+
+VALIDATORS: dict[str, Callable[[dict[str, Any]], tuple[bool, str]]] = {
+    "unitRegression": validate_unit,
+    "packageSmoke": validate_package,
+    "browserEvidence": validate_browser,
+    "renderedCanary": validate_canary,
+    "deploymentPreflight": validate_preflight,
+}
+
+
+def inspect_check(name: str, path: Path, project: Path) -> dict[str, Any]:
+    result: dict[str, Any] = {"state": "inconclusive", "configured": path.is_file(), "path": display_path(path, project)}
+    if not path.is_file():
+        result["reason"] = "required adapter evidence is unavailable"
+        return result
+    try:
+        payload = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as error:
+        result.update({"state": "failed", "reason": f"evidence is not valid JSON: {error}"})
+        return result
+    if not isinstance(payload, dict):
+        result.update({"state": "failed", "reason": "evidence root must be an object"})
+        return result
+    valid, reason = VALIDATORS[name](payload)
+    result.update({"state": "passed" if valid else "failed", "reason": reason})
+    return result
+
+
+def readiness(project: Path, paths: dict[str, Path], output: Path | None = None) -> int:
+    checks = {name: inspect_check(name, path, project) for name, path in paths.items()}
+    states = {item["state"] for item in checks.values()}
+    status = "failed" if "failed" in states else "inconclusive" if "inconclusive" in states else "passed"
+    report = {
+        "schemaVersion": "maggie-deployment-readiness.v1",
+        "generatedAt": datetime.now(timezone.utc).isoformat(),
+        "project": display_path(project, project),
+        "status": status,
+        "checks": checks,
+        "nextAction": "resolve failed evidence before release" if status == "failed" else "collect the missing host adapter evidence" if status == "inconclusive" else "all declared readiness evidence passed",
+    }
+    if output:
+        destination = output if output.is_absolute() else project / output
+        destination.parent.mkdir(parents=True, exist_ok=True)
+        destination.write_text(json.dumps(report, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+        report["output"] = display_path(destination, project)
+    print(json.dumps(report, indent=2, ensure_ascii=False))
+    return 0 if status == "passed" else 1
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--project", type=Path, default=Path.cwd())
+    parser.add_argument("--unit-report", type=Path, default=Path(".maggie/verification/unit-regression.json"))
+    parser.add_argument("--package-report", type=Path, default=Path(".maggie/verification/package-smoke.json"))
+    parser.add_argument("--browser-report", type=Path, default=Path(".maggie/verification/browser-evidence.json"))
+    parser.add_argument("--rendered-canary", type=Path, default=Path(".maggie/deployment-canary.json"))
+    parser.add_argument("--deployment-preflight", type=Path, default=Path(".maggie/release-preflight.json"))
+    parser.add_argument("--output", type=Path)
+    args = parser.parse_args()
+    project = args.project.resolve()
+    if not project.is_dir():
+        parser.error(f"project directory does not exist: {project}")
+    paths = {
+        name: (getattr(args, option).resolve() if getattr(args, option).is_absolute() else project / getattr(args, option))
+        for name, option in CHECKS
+    }
+    try:
+        return readiness(project, paths, args.output)
+    except (OSError, ValueError) as error:
+        print(f"BLOCKED: maggie deployment readiness: {error}", file=sys.stderr)
+        return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/bundled-tools/clis/maggie_localization.py

@@ -12,7 +12,7 @@ from datetime import datetime, timezone
 from pathlib import Path
 
 sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "runtime"))
-from content_localization import LANGUAGES, MARKETS, OPERATIONS, parse_locale, protected_field_changes, stale, valid_locale, validate_translation
+from content_localization import LANGUAGES, MARKETS, OPERATIONS, parse_locale, protected_field_changes, stale, valid_locale, validate_operation_quality, validate_translation
 from localization_runner import generate, process_adapter
 
 
@@ -250,6 +250,8 @@ def validate_job(path: Path, source_path: Path | None = None, render_path: Path
         errors.append("generationContract mode must match operation")
     if job.get("operation") == "rewrite" and not generation.get("allowStructuralRewrite"):
         errors.append("rewrite requires structural rewrite permission")
+    if job.get("operation") == "polish" and job.get("sourceLanguage") != job.get("targetLanguage"):
+        errors.append("polish must keep sourceLanguage and targetLanguage identical")
     errors.extend(validate_translation({
         "contentId": job.get("contentId"), "lang": job.get("targetLanguage"),
         "locale": job.get("targetLocale"), "translationGroupId": job.get("translationGroupId", f"tg-{job.get('contentId')}"),
@@ -260,6 +262,8 @@ def validate_job(path: Path, source_path: Path | None = None, render_path: Path
         })
     }, expected_lang=job.get("targetLanguage")))
     errors.extend(f"protected field changed without approval: {field}" for field in protected_field_changes(job.get("content", {}), translation))
+    quality_errors, quality = validate_operation_quality(job.get("content", {}), translation, job.get("operation", ""), job.get("review"))
+    errors.extend(quality_errors)
     if source_path:
         errors.extend(validate_source(source_path, job.get("sourceRevision")))
         source = load(source_path)
@@ -269,7 +273,7 @@ def validate_job(path: Path, source_path: Path | None = None, render_path: Path
             errors.append("translation sourceStringIds must link every extracted source string")
     if render_path:
         errors.extend(validate_render_report(render_path))
-    return {"passed": not errors, "errors": errors, "jobId": job.get("jobId"), "status": job.get("status")}
+    return {"passed": not errors, "errors": errors, "jobId": job.get("jobId"), "status": job.get("status"), "quality": quality}
 
 
 def preview(path: Path) -> int:

package/bundled-tools/runtime/content_localization.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+from collections import Counter
 import re
 from typing import Any, Iterable
 
@@ -17,6 +18,10 @@ MARKETS = {"global", "uk", "us"}
 STATUSES = {"missing", "draft", "machine_translated", "needs_review", "approved", "published", "archived"}
 OPERATIONS = {"translate", "polish", "rewrite", "localise", "rebrand", "manual_edit"}
 PROTECTED_FIELDS = {"price", "currency", "rating", "provider", "providerId", "bookingUrl", "paymentUrl", "legalClaims", "healthClaims", "contentId", "slug", "canonicalUrl", "translationGroupId"}
+QUALITY_OPERATIONS = {"polish", "rewrite"}
+QUALITY_META_FIELDS = {"identity", "contentId", "contentType", "sourceRevision", "translationStatus", "isIndexable", "provenance", "sourceStringIds", "qualityEvidence", "humanReviewStatus"}
+FACT_TOKEN_PATTERN = re.compile(r"https?://[^\s<>]+|[\w.+-]+@[\w.-]+\.[A-Za-z]{2,}|(?:£|\$|€|¥|₹)\s*\d[\d,.]*|\b\d[\d,.]*%|\b\d[\d,.]*\b", re.UNICODE)
+PLACEHOLDER_PATTERN = re.compile(r"\{\{[^}]+\}\}|\$\{[^}]+\}|\b(?:TODO|TBD|lorem ipsum)\b", re.IGNORECASE)
 
 
 class TranslationIndex:
@@ -162,3 +167,135 @@ def protected_field_changes(source: Any, translation: Any) -> list[str]:
     if not isinstance(source, dict) or not isinstance(translation, dict):
         return []
     return [field for field in sorted(PROTECTED_FIELDS) if field in source and field in translation and source[field] != translation[field]]
+
+
+def _copy_payload(value: Any) -> Any:
+    """Remove identity/approval metadata before comparing editorial structure."""
+    if isinstance(value, dict):
+        return {
+            key: _copy_payload(item)
+            for key, item in value.items()
+            if key not in QUALITY_META_FIELDS and key not in PROTECTED_FIELDS
+        }
+    if isinstance(value, list):
+        return [_copy_payload(item) for item in value]
+    return value
+
+
+def _copy_text(value: Any) -> str:
+    if isinstance(value, dict):
+        return "\n".join(part for part in (_copy_text(item) for item in value.values()) if part)
+    if isinstance(value, list):
+        return "\n".join(part for part in (_copy_text(item) for item in value) if part)
+    return str(value).strip() if isinstance(value, str) else ""
+
+
+def _copy_metrics(text: str) -> dict[str, int | bool]:
+    normalized = text.strip()
+    sentences = [item for item in re.split(r"[.!?。！？]+", normalized) if item.strip()]
+    words = re.findall(r"\w+(?:['’\-]\w+)*", normalized, re.UNICODE)
+    sentence_lengths = [len(re.findall(r"\w+", item, re.UNICODE)) for item in sentences]
+    return {
+        "characters": len(normalized),
+        "words": len(words),
+        "sentences": len(sentences),
+        "paragraphs": len([item for item in re.split(r"\n\s*\n", normalized) if item.strip()]),
+        "headings": len(re.findall(r"(?im)^\s{0,3}(?:#{1,6}\s+|<h[1-6]\b)", normalized)),
+        "listItems": len(re.findall(r"(?im)^\s*(?:[-*+]\s+|\d+[.)]\s+|<li\b)", normalized)),
+        "maxSentenceWords": max(sentence_lengths, default=0),
+        "placeholders": len(PLACEHOLDER_PATTERN.findall(normalized)),
+        "repeatedWhitespace": len(re.findall(r"[ \t]{2,}", normalized)),
+    }
+
+
+def _fact_tokens(text: str) -> Counter[str]:
+    return Counter(token.casefold().rstrip(".,;:)") for token in FACT_TOKEN_PATTERN.findall(text))
+
+
+def _structure_signature(value: Any) -> tuple[Any, ...]:
+    if isinstance(value, dict):
+        return ("object", tuple((key, _structure_signature(item)) for key, item in sorted(value.items())))
+    if isinstance(value, list):
+        return ("list", len(value), tuple(_structure_signature(item) for item in value))
+    if isinstance(value, str):
+        metrics = _copy_metrics(value)
+        return ("text", metrics["paragraphs"], metrics["headings"], metrics["listItems"], metrics["sentences"])
+    if value is None:
+        return ("null",)
+    return (type(value).__name__,)
+
+
+def validate_operation_quality(source: Any, translation: Any, operation: str, review: Any = None) -> tuple[list[str], dict[str, Any]]:
+    """Run conservative, dependency-free checks for polish and rewrite jobs.
+
+    These checks cover observable copy structure and protected fact tokens. They
+    intentionally do not claim semantic equivalence; every applicable result
+    carries a mandatory human-review signal.
+    """
+    report: dict[str, Any] = {
+        "operation": operation,
+        "applicable": operation in QUALITY_OPERATIONS,
+        "method": "deterministic-copy-heuristics",
+    }
+    if operation not in QUALITY_OPERATIONS:
+        return [], report
+    source_copy = _copy_payload(source)
+    translation_copy = _copy_payload(translation)
+    source_text = _copy_text(source_copy)
+    translation_text = _copy_text(translation_copy)
+    source_metrics = _copy_metrics(source_text)
+    translation_metrics = _copy_metrics(translation_text)
+    source_facts = _fact_tokens(source_text)
+    translation_facts = _fact_tokens(translation_text)
+    changed_fact_count = sum((source_facts - translation_facts).values()) + sum((translation_facts - source_facts).values())
+    normalized_source = re.sub(r"\s+", " ", source_text).strip().casefold()
+    normalized_translation = re.sub(r"\s+", " ", translation_text).strip().casefold()
+    structure_changed = _structure_signature(source_copy) != _structure_signature(translation_copy)
+    clarity_signal = (
+        translation_metrics["maxSentenceWords"] < source_metrics["maxSentenceWords"]
+        or translation_metrics["sentences"] > source_metrics["sentences"]
+        or translation_metrics["repeatedWhitespace"] < source_metrics["repeatedWhitespace"]
+        or translation_metrics["placeholders"] < source_metrics["placeholders"]
+    )
+    declared_clarity = isinstance(translation, dict) and isinstance(translation.get("qualityEvidence"), dict) and translation["qualityEvidence"].get("clarityImproved") is True
+    human_review = review if isinstance(review, dict) else {}
+    review_approved = human_review.get("decision") == "approve" and bool(human_review.get("reviewer"))
+    errors: list[str] = []
+    if not source_text:
+        errors.append(f"{operation} quality requires source copy text")
+    if not translation_text:
+        errors.append(f"{operation} quality requires generated copy text")
+    if changed_fact_count:
+        errors.append(f"{operation} output changed {changed_fact_count} protected fact token(s)")
+    if operation == "polish":
+        if normalized_source and normalized_source == normalized_translation:
+            errors.append("polish output is unchanged")
+        if translation_metrics["placeholders"] > source_metrics["placeholders"]:
+            errors.append("polish output introduced unresolved placeholders")
+        if source_text and translation_text and not (clarity_signal or declared_clarity):
+            errors.append("polish output has no deterministic clarity-improvement signal")
+    if operation == "rewrite":
+        if normalized_source and normalized_source == normalized_translation:
+            errors.append("rewrite output is unchanged")
+        if source_text and translation_text and not structure_changed:
+            errors.append("rewrite output did not change copy structure")
+    report.update({
+        "source": source_metrics,
+        "output": translation_metrics,
+        "checks": {
+            "nonEmpty": bool(source_text and translation_text),
+            "changed": bool(normalized_source != normalized_translation),
+            "protectedFactsPreserved": changed_fact_count == 0,
+            "structureChanged": structure_changed,
+            "clarityImproved": bool(clarity_signal or declared_clarity) if operation == "polish" else None,
+            "clarityEvidence": "deterministic" if clarity_signal else "declared" if declared_clarity else "missing",
+        },
+        "humanReview": {
+            "required": True,
+            "status": "approved" if review_approved else "required",
+            "semanticEquivalence": "not-certified",
+            "reason": "heuristics do not replace human meaning review",
+        },
+        "status": "passed" if not errors else "failed",
+    })
+    return errors, report

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@topy-ai/maggie",
-  "version": "0.7.19",
+  "version": "0.7.21",
   "description": "Install and manage Maggie Skills for AI coding agents",
   "license": "MIT",
   "type": "module",

package/references/content-localization-contract.md

@@ -61,6 +61,15 @@ Supported operations are distinct: `translate`, `polish`, `rewrite`,
 source. A source revision change marks dependent translations stale. Fallback
 content is never indexable.
 
+`polish` and `rewrite` validation includes deterministic output checks. Polish
+must keep the source language, change the copy, preserve protected fact tokens,
+and show a clarity signal (shorter maximum sentence, clearer sentence
+segmentation, placeholder reduction, or explicit quality evidence). Rewrite
+must change the copy and its observable structure, while preserving protected
+fact tokens. These are conservative heuristics, not semantic equivalence
+proof: every result contains `quality.humanReview.required: true` and marks
+semantic equivalence as `not-certified` until a named reviewer approves it.
+
 The following are protected by default: price, currency, rating, provider
 facts, booking URL, legal/health claims, content ID, slug, canonical owner,
 and translation group. Changes require structured approval and evidence.