@topy-ai/maggie 0.7.5 → 0.7.6

package/README.md

@@ -93,7 +93,7 @@ maggie dash install | init | status | migrate | cms ...
 maggie dash transition ...      # explicit content approval transition
 maggie dash variant ...         # service variant create/review/preview/publish
 maggie dash sections ...        # validate/catalogue/identity keys
-maggie agent-content write ...  # host-authorized content bridge
+maggie agent-content write ...  # host-authorized, origin-bound content bridge
 maggie verification coverage ... # changed surface/locale evidence gate
 maggie clone ...                 # authorized homepage capture
 maggie design ...                # authorized interior-page design
@@ -112,6 +112,18 @@ maggie design icon-inventory --source-dir src --runtime assets/icons.css
 maggie api lifecycle | site-audit | ops audit
 ```
 
+Agent content writes must declare the exact host origin that minted the
+short-lived token; the CLI rejects nested credential keys and cross-origin
+redirects:
+
+```bash
+maggie agent-content write \
+  --url https://example.test/api/maggie/agent-content.json \
+  --allowed-origin https://example.test \
+  --token-env MAGGIE_CONTENT_TOKEN \
+  --payload .maggie/content-operation.json
+```
+
 Run `maggie --help` for the complete syntax. `maggie-emdash` is migration
 history only and is not an installable package skill.
 
@@ -194,8 +206,8 @@ artifact schemas.
 Recommended upgrade sequence for the current release:
 
 ```bash
-npx @topy-ai/maggie@0.7.5 update --project . --force
-npx @topy-ai/maggie@0.7.5 cleanup --project .
+npx @topy-ai/maggie@0.7.6 update --project . --force
+npx @topy-ai/maggie@0.7.6 cleanup --project .
 ```
 
 Maintainers should pass npm credentials through the repository helper, never
@@ -205,7 +217,7 @@ as a command-line argument:
 node scripts/publish-npm.mjs --maggie-env-file ../.env
 ```
 
-The 0.7.5 workflow adds the installable MaggieDash admin distribution and
+The 0.7.6 workflow adds the installable MaggieDash admin distribution and
 audited CMS operations (`cms revisions`,
 `trash`, `restore`, `schedule`, `publish-due`, `duplicate`, `redirect`, and
 signed `preview`). It also adds a read-only MaggieDash `--diff`/`--dry-run`
@@ -216,7 +228,12 @@ adds stable section identities and reusable section presets, a machine-readable
 MaggieDash section registry, a short-lived agent content bridge, restart gates
 for out-of-band translation writes, deployment release-runner generation,
 disk-versus-manifest skill inventory checks, and changed-surface/locale
-verification. The release retains the existing service matching,
+verification. Surface evidence is route-level and rejects duplicate
+observations; every route must include status, canonical, indexability, and
+required metadata checks. Agent content writes require an explicit approved
+origin, same-origin redirects, and recursive credential validation. Feedback
+submissions persist and print only an allowlisted acknowledgement. The release
+retains the existing service matching,
 localization, seed-manifest, lockfile/analytics, sitemap, deployment and
 rollback workflows.
 
@@ -308,6 +325,9 @@ maggie feedback submit .maggie/feedback/<feedback-id>.json \
 Submission is never implicit. Project paths, source files, logs, and secrets
 are excluded by default. The hosted endpoint stores the normalized feedback in
 NoBlox for maintainer review; it does not automatically create a GitHub Issue.
+The local submission record and command output keep only `status`, `feedbackId`,
+and `requestId` from the provider acknowledgement; arbitrary response bodies
+are not persisted or printed.
 For public reports, use the repository's
 [GitHub Issue Forms](https://github.com/TOPY-AI-LTD/ai-cmo-skills/issues/new/choose).
 

package/README.zh-TW.md

@@ -8,7 +8,7 @@ Codex、Claude Code 與相容的 coding agents。
 ## 安裝
 
 ```bash
-npx @topy-ai/maggie@0.7.5 init --agent all
+npx @topy-ai/maggie@0.7.6 init --agent all
 npx @topy-ai/maggie doctor --project .
 ```
 

package/bundled-contracts/maggiedash/agent-content-v1.json

@@ -3,12 +3,14 @@
   "$id": "https://maggiedash.noblox.app/contracts/agent-content-v1.schema.json",
   "title": "MaggieDash agent content bridge v1",
   "type": "object",
-  "required": ["method", "authorization", "tokenLifetime", "databaseCredentials"],
+  "required": ["method", "authorization", "tokenLifetime", "databaseCredentials", "originPolicy", "payloadSecurity"],
   "properties": {
     "method": {"const": "POST"},
     "authorization": {"const": "Bearer short-lived session token"},
     "tokenLifetime": {"const": "terminal session"},
     "databaseCredentials": {"const": "never exposed to agent"},
+    "originPolicy": {"const": "explicit approved origin allowlist; redirects remain same-origin"},
+    "payloadSecurity": {"const": "recursive sensitive-key rejection and response redaction"},
     "writes": {"type": "array", "items": {"enum": ["validated content operation", "revision", "audit event"]}}
   },
   "additionalProperties": false

package/bundled-references/localization-extraction-render-prd.md

@@ -0,0 +1,55 @@
+# Localization source extraction and rendered validation
+
+## Problem
+
+`maggie-content-localization` currently accepts a prepared `content.json` and
+validates the resulting job. It does not extract translatable strings from a
+real project, so malformed JSX fragments, multiline text nodes, untranslated
+Latin terms, and script mismatches can pass the record validator while still
+breaking the rendered page.
+
+## Proposed stable workflow
+
+Add a read-only extractor and a separate rendered validation gate:
+
+```bash
+maggie localization extract --project . --source-dir src \
+  --routes-file docs/routes.tsv --output .maggie/localization/source.json
+maggie localization plan --content .maggie/localization/source.json ...
+maggie localization validate .maggie/localization/<job>.json \
+  --source .maggie/localization/source.json \
+  --render-report .maggie/localization/rendered.json
+```
+
+The extractor must use an AST-aware adapter for JSX/TSX/Astro/Vue/Svelte
+where available, with a conservative HTML fallback. It must never rewrite
+source files. Each extracted string records file, line, route, source hash,
+attribute/text-node kind, and an explicit translatable/non-translatable
+decision. Fragments containing braces or JavaScript operators are rejected or
+reported for review, not interpreted as text.
+
+The validation report must cover multiline nodes, required metadata, protected
+facts, script expectations, glossary/allowlist exceptions, and browser output.
+The rendered report must identify route, screenshot, console errors, failed
+asset requests, placeholder count, and untranslated required strings. Any
+failure keeps the locale non-indexable and blocks publish.
+
+## Acceptance criteria
+
+- JSX conditionals and expressions are never emitted as translation strings.
+- Text nodes spanning multiple lines are extracted and tested.
+- Script/Latin-word checks support all registered languages and configurable
+  proper-noun/glossary allowlists.
+- Source and translated strings are linked by stable IDs and source revision.
+- A clean extraction plus clean rendered report is required before approval;
+  record-only validation is not sufficient.
+- Unit fixtures cover Astro/JSX/Vue/Svelte/HTML, false positives, protected
+  facts, multiline nodes, script checks, and route-level browser errors.
+- The feature remains local-first, dependency-adaptable, redacted, and
+  backward-compatible with existing `content.json` input.
+
+## Out of scope
+
+Automatic translation quality scoring, silent source rewriting, and automatic
+publish. Translation generation and owner/Admin approval remain separate
+operations.

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

@@ -114,7 +114,7 @@ line numbers, routes, and attribute/text-node kinds while skipping scripts,
 styles, SVG, and dynamic expressions. Supplying source and render reports to
 `validate` makes the checks fail closed; the prepared `content.json` flow
 remains backward-compatible without those artifacts. See
-[`docs/localization-extraction-render-prd.md`](../../docs/localization-extraction-render-prd.md)
+[`docs/localization-extraction-render-prd.md`](../../references/localization-extraction-render-prd.md)
 for the artifact contract and limitations.
 
 Use the shared translation index and route predicates from

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

@@ -52,14 +52,18 @@ bridge rather than editing release files or receiving database credentials:
 ```bash
 maggie agent-content write \
   --url https://example.test/api/maggie/agent-content.json \
+  --allowed-origin https://example.test \
   --token-env MAGGIE_CONTENT_TOKEN --payload .maggie/content-operation.json
 ```
 
 The host mints a short-lived session token. The bridge uses `POST` with
-`Authorization: Bearer`, delegates to the ordinary save/revision/audit path,
-and returns 401/422 for invalid authority or content. Never put database
-credentials or the short-lived token in the payload or generated reports. See
-the [agent content contract](../../contracts/maggiedash/agent-content-v1.json).
+`Authorization: Bearer`, requires the exact approved host origin, rejects
+cross-origin redirects, delegates to the ordinary save/revision/audit path,
+and returns 401/422 for invalid authority or content. Nested credential-like
+payload keys are rejected and response values are recursively redacted. Never
+put database credentials or the short-lived token in the payload or generated
+reports. See
+the [agent content contract](../../bundled-contracts/maggiedash/agent-content-v1.json).
 
 ## Workflow
 
@@ -161,7 +165,7 @@ the route returns 404 and self/chain redirects are rejected. Preview tokens
 are short-lived HMAC-signed tokens; preview responses must use a real preview
 URL with `noindex`, `X-Robots-Tag: noindex`, and `Cache-Control: no-store`.
 Never place the secret in source control or generated reports. See the
-provider-neutral [MaggieDash contract set](../../contracts/maggiedash/README.md).
+provider-neutral [MaggieDash contract set](../../bundled-contracts/maggiedash/README.md).
 
 Reusable arrangements are stored without page-specific section IDs and expand
 into ordinary editable sections with fresh IDs on every insert. Use the

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

@@ -44,7 +44,10 @@ maggie feedback submit .maggie/feedback/<feedback-id>.json \
 
 Only HTTPS endpoints are accepted. Project paths, file contents, secrets, and
 logs are excluded by default. `--allow-project-context` is an explicit opt-in;
-even then, send only a short public-safe context note.
+even then, send only a short public-safe context note. After submission, the
+local record and stdout retain only the provider acknowledgement fields
+`status`, `feedbackId`, and `requestId`; arbitrary response bodies are never
+stored or printed.
 
 ## Lifecycle
 

package/bundled-skills/maggie-seo-geo/SKILL.md

@@ -30,10 +30,14 @@ maggie verification coverage \
   --evidence .maggie/surface-coverage.json
 ```
 
-The evidence must contain one observation for every declared surface/locale
-pair with a status and `passed: true`. Public-page checks alone cannot close an
-admin or API change, and one source-language rendering cannot close a
-localized change.
+The evidence must contain one observation for every declared
+surface/locale/route key with a unique `route`, HTTP `status`, `passed: true`,
+`canonical: true`, a boolean `indexable`, and a `metadata` object containing
+every field named by that surface's `requiredMetadata`. Duplicate keys fail;
+the verifier preserves the observation count and reports the duplicate and
+the original failure instead of allowing a later passing observation to hide
+it. Public-page checks alone cannot close an admin or API change, and one
+source-language rendering cannot close a localized change.
 
 Crawl reports include `summary.byLocaleTemplate` with total, passed, failed
 and failed URLs per declared locale and template. Regions/scripts remain

package/bundled-tools/clis/maggie_agent_content.py

@@ -9,32 +9,94 @@ import os
 import sys
 from pathlib import Path
 from urllib.error import HTTPError, URLError
-from urllib.request import Request, urlopen
+from urllib.parse import urlparse
+from urllib.request import HTTPRedirectHandler, Request, build_opener
 
 
-SENSITIVE_KEYS = {"databaseUrl", "databaseURL", "password", "secret", "token", "apiKey"}
+SENSITIVE_KEYS = {"databaseurl", "password", "secret", "token", "apikey", "authorization", "privatekey", "connectionstring", "clientsecret"}
+SENSITIVE_KEY_PARTS = ("databaseurl", "password", "secret", "token", "apikey", "authorization", "privatekey", "connectionstring")
+
+
+def normalized_key(value: object) -> str:
+    return "".join(character for character in str(value).lower() if character.isalnum())
+
+
+def is_sensitive_key(value: object) -> bool:
+    key = normalized_key(value)
+    return key in SENSITIVE_KEYS or any(part in key for part in SENSITIVE_KEY_PARTS)
+
+
+def validate_no_credentials(value: object) -> None:
+    if isinstance(value, dict):
+        for key, child in value.items():
+            if is_sensitive_key(key):
+                raise ValueError("payload must not contain credentials; use the short-lived token environment variable")
+            validate_no_credentials(child)
+    elif isinstance(value, list):
+        for child in value:
+            validate_no_credentials(child)
 
 
 def validate_payload(value: object) -> dict:
     if not isinstance(value, dict):
         raise ValueError("payload must be a JSON object")
-    forbidden = sorted(SENSITIVE_KEYS.intersection(value))
-    if forbidden:
-        raise ValueError("payload must not contain credentials; use the short-lived token environment variable")
+    validate_no_credentials(value)
     if not value.get("op"):
         raise ValueError("payload.op is required")
     return value
 
 
-def write(url: str, token_env: str, payload: dict, timeout: int = 30) -> dict:
+def origin(url: str) -> str:
+    parsed = urlparse(url)
+    if parsed.scheme not in {"http", "https"} or not parsed.hostname or parsed.username or parsed.password or parsed.query or parsed.fragment:
+        raise ValueError("content host must be an absolute HTTP(S) URL without credentials or query parameters")
+    try:
+        port = parsed.port
+    except ValueError as error:
+        raise ValueError("content host origin has an invalid port") from error
+    default = (parsed.scheme == "http" and port == 80) or (parsed.scheme == "https" and port == 443)
+    return f"{parsed.scheme.lower()}://{parsed.hostname.lower()}" + (f":{port}" if port and not default else "")
+
+
+def approved_origin(value: str) -> str:
+    parsed = urlparse(value)
+    if parsed.path not in {"", "/"}:
+        raise ValueError("approved origin must not contain a path")
+    return origin(value)
+
+
+class SameOriginRedirectHandler(HTTPRedirectHandler):
+    def __init__(self, approved_origin: str):
+        super().__init__()
+        self.approved_origin = approved_origin
+
+    def redirect_request(self, req, fp, code, msg, headers, newurl):  # noqa: N802
+        if origin(newurl) != self.approved_origin:
+            raise ValueError("content host redirected to a different origin")
+        return super().redirect_request(req, fp, code, msg, headers, newurl)
+
+
+def redact_response(value: object) -> object:
+    if isinstance(value, dict):
+        return {key: "[REDACTED]" if is_sensitive_key(key) else redact_response(child) for key, child in value.items()}
+    if isinstance(value, list):
+        return [redact_response(child) for child in value]
+    return value
+
+
+def write(url: str, token_env: str, payload: dict, allowed_origin: str, timeout: int = 30) -> dict:
     token = os.environ.get(token_env, "")
     if not token:
         raise ValueError(f"{token_env} is not set")
+    approved = approved_origin(allowed_origin)
+    if origin(url) != approved:
+        raise ValueError("content host URL must match the approved origin")
     request = Request(url, data=json.dumps(payload, ensure_ascii=False).encode("utf-8"), method="POST", headers={
         "Accept": "application/json", "Content-Type": "application/json", "Authorization": f"Bearer {token}",
     })
     try:
-        with urlopen(request, timeout=timeout) as response:
+        opener = build_opener(SameOriginRedirectHandler(approved))
+        with opener.open(request, timeout=timeout) as response:
             raw = response.read().decode("utf-8", errors="replace")
             status = response.status
     except HTTPError as error:
@@ -46,10 +108,7 @@ def write(url: str, token_env: str, payload: dict, timeout: int = 30) -> dict:
         body = json.loads(raw) if raw else {}
     except json.JSONDecodeError:
         body = {"error": "host returned non-JSON"}
-    if isinstance(body, dict):
-        for key in SENSITIVE_KEYS:
-            body.pop(key, None)
-    return {"status": status, "passed": 200 <= status < 300, "response": body}
+    return {"status": status, "passed": 200 <= status < 300, "response": redact_response(body)}
 
 
 def main() -> int:
@@ -57,13 +116,14 @@ def main() -> int:
     sub = parser.add_subparsers(dest="command", required=True)
     command = sub.add_parser("write", help="POST a validated content operation")
     command.add_argument("--url", required=True)
+    command.add_argument("--allowed-origin", required=True, help="exact HTTP(S) origin approved by the host")
     command.add_argument("--token-env", default="MAGGIE_CONTENT_TOKEN")
     command.add_argument("--payload", type=Path, required=True)
     command.add_argument("--timeout", type=int, default=30)
     args = parser.parse_args()
     try:
         payload = validate_payload(json.loads(args.payload.read_text(encoding="utf-8")))
-        result = write(args.url, args.token_env, payload, args.timeout)
+        result = write(args.url, args.token_env, payload, args.allowed_origin, args.timeout)
         print(json.dumps(result, ensure_ascii=False, indent=2))
         return 0 if result["passed"] else 1
     except (OSError, ValueError, RuntimeError) as error:

package/bundled-tools/clis/maggie_feedback.py

@@ -20,6 +20,9 @@ from urllib.request import Request, urlopen
 
 DEFAULT_ENDPOINT = "https://feedback.noblox.app/api/feedback"
 SECRET_RE = re.compile(r"(?i)(bearer\s+|(?:api[_-]?key|token|secret|password|npm_config[^=]*|authorization)\s*[=:]\s*)[^\s,;]+")
+VERSION_RE = re.compile(r"\d+\.\d+\.\d+(?:[-+][A-Za-z0-9.-]+)?")
+ACKNOWLEDGEMENT_KEYS = ("status", "feedbackId", "requestId")
+REPO_ROOT = Path(__file__).resolve().parents[2]
 
 
 def now() -> str:
@@ -35,17 +38,29 @@ def project_fingerprint(project: Path) -> str:
 
 
 def installed_version(project: Path) -> str:
-    """Resolve the version from the runtime wrapper or project install state."""
+    """Resolve the exact runtime version and fail closed on source drift."""
     if os.environ.get("MAGGIE_VERSION"):
-        return safe_text(os.environ["MAGGIE_VERSION"])
-    for path in (project / ".maggie" / "install.json", project / "VERSION"):
+        value = safe_text(os.environ["MAGGIE_VERSION"])
+        return value if VERSION_RE.fullmatch(value) else "unknown"
+    install_path = project / ".maggie" / "install.json"
+    try:
+        value = json.loads(install_path.read_text(encoding="utf-8")).get("version", "")
+        if VERSION_RE.fullmatch(str(value)):
+            return str(value)
+    except (OSError, ValueError, json.JSONDecodeError, AttributeError):
+        pass
+
+    source_versions = []
+    for path in (REPO_ROOT / "VERSION", REPO_ROOT / "packages" / "maggie-cli" / "package.json"):
         try:
             value = json.loads(path.read_text(encoding="utf-8")) if path.suffix == ".json" else path.read_text(encoding="utf-8").strip()
             if isinstance(value, dict): value = value.get("version", "")
-            if re.fullmatch(r"\d+\.\d+\.\d+(?:[-+][A-Za-z0-9.-]+)?", str(value)):
-                return str(value)
+            if VERSION_RE.fullmatch(str(value)):
+                source_versions.append(str(value))
         except (OSError, ValueError, json.JSONDecodeError):
             continue
+    if source_versions and len(set(source_versions)) == 1:
+        return source_versions[0]
     return "unknown"
 
 
@@ -124,6 +139,18 @@ def to_markdown(data: dict) -> str:
     return "\n".join(lines)
 
 
+def acknowledgement(value: object) -> dict:
+    """Keep only safe, scalar acknowledgement fields from a provider response."""
+    if not isinstance(value, dict):
+        return {}
+    result = {}
+    for key in ACKNOWLEDGEMENT_KEYS:
+        item = value.get(key)
+        if isinstance(item, (str, int, float, bool)):
+            result[key] = safe_text(item)
+    return result
+
+
 def read_feedback(path: Path) -> dict:
     return load_json(path)
 
@@ -152,9 +179,10 @@ def submit(args: argparse.Namespace) -> int:
             result = json.loads(raw) if raw else {}
     except (HTTPError, URLError, TimeoutError) as error:
         raise RuntimeError(f"feedback submission failed: {error}") from error
-    data["submission"] = {"status": "submitted", "endpoint": endpoint, "submittedAt": now(), "response": result if isinstance(result, dict) else {"value": result}}
+    ack = acknowledgement(result)
+    data["submission"] = {"status": "submitted", "endpoint": endpoint, "submittedAt": now(), "acknowledgement": ack}
     path.write_text(json.dumps(data, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
-    print(json.dumps({"feedbackId": data["feedbackId"], "status": "submitted", "response": result}, indent=2, ensure_ascii=False))
+    print(json.dumps({"feedbackId": data["feedbackId"], "status": "submitted", "acknowledgement": ack}, indent=2, ensure_ascii=False))
     return 0
 
 

package/bundled-tools/runtime/surface_coverage.py

@@ -6,6 +6,7 @@ from typing import Any
 
 
 SCHEMA = "maggie-surface-coverage.v1"
+REQUIRED_EVIDENCE = ("status", "canonical", "indexability", "metadata")
 
 
 def validate_contract(contract: object) -> dict[str, Any]:
@@ -23,26 +24,99 @@ def validate_contract(contract: object) -> dict[str, Any]:
         if not isinstance(item, dict) or not item.get("name") or not isinstance(item.get("routes"), list) or not item["routes"] or not isinstance(item.get("locales"), list) or not item["locales"]:
             errors.append(f"surfaces[{index}] needs name, routes, and locales")
             continue
+        required = item.get("requiredEvidence")
+        if not isinstance(required, list) or not required or any(value not in REQUIRED_EVIDENCE for value in required):
+            errors.append(f"surfaces[{index}] needs valid requiredEvidence")
+        metadata = item.get("requiredMetadata")
+        if not isinstance(metadata, list) or any(not isinstance(value, str) or not value for value in metadata):
+            errors.append(f"surfaces[{index}] needs requiredMetadata")
+        route_values = [str(route) for route in item["routes"]]
+        if len(route_values) != len(set(route_values)):
+            errors.append(f"duplicate route in surface: {item['name']}")
+        locale_values = [str(locale) for locale in item["locales"]]
+        if len(locale_values) != len(set(locale_values)):
+            errors.append(f"duplicate locale in surface: {item['name']}")
         for locale in item["locales"]:
             key = (str(item["name"]), str(locale))
             if key in seen:
                 errors.append(f"duplicate surface/locale: {key[0]}/{key[1]}")
             seen.add(key)
-    return {"schemaVersion": SCHEMA, "passed": not errors, "errors": errors, "expectedPairs": sorted(f"{surface}/{locale}" for surface, locale in seen)}
+    expected = [f"{item['name']}/{locale}/{route}" for item in surfaces if isinstance(item, dict) and item.get("name") for locale in item.get("locales", []) for route in item.get("routes", [])]
+    return {"schemaVersion": SCHEMA, "passed": not errors, "errors": errors, "expectedPairs": sorted(f"{surface}/{locale}" for surface, locale in seen), "expectedRoutes": sorted(expected)}
+
+
+def _truthy_check(value: object) -> bool:
+    if value is True:
+        return True
+    return isinstance(value, dict) and value.get("ok") is True
+
+
+def _key_text(key: tuple[str, str, str]) -> str:
+    return f"{key[0]}/{key[1]}|{key[2]}"
+
+
+def _route_result(item: dict[str, Any], required: list[str], required_metadata: list[str]) -> tuple[bool, list[str]]:
+    missing: list[str] = []
+    checks = item.get("checks") if isinstance(item.get("checks"), dict) else {}
+    if "status" in required:
+        try:
+            if int(item.get("status")) >= 400:
+                missing.append("status")
+        except (TypeError, ValueError):
+            missing.append("status")
+    if "canonical" in required and not _truthy_check(item.get("canonical", checks.get("canonical"))):
+        missing.append("canonical")
+    indexability = item.get("indexable", item.get("indexability", checks.get("indexability")))
+    if "indexability" in required and not isinstance(indexability, bool):
+        missing.append("indexability")
+    if "metadata" in required:
+        metadata = item.get("metadata") if isinstance(item.get("metadata"), dict) else checks.get("metadata")
+        if not isinstance(metadata, dict) or any(metadata.get(field) is not True for field in required_metadata):
+            missing.append("metadata")
+    if item.get("passed") is not True:
+        missing.append("passed")
+    return not missing, sorted(set(missing))
 
 
 def compare(contract: dict[str, Any], observations: object) -> dict[str, Any]:
     checked = validate_contract(contract)
     if not checked["passed"]:
         return {**checked, "observedPairs": [], "missing": [], "failed": []}
-    expected = {(str(item["name"]), str(locale)) for item in contract["surfaces"] for locale in item["locales"]}
-    observed: dict[tuple[str, str], dict[str, Any]] = {}
+    expected = {(str(item["name"]), str(locale), str(route)) for item in contract["surfaces"] for locale in item["locales"] for route in item["routes"]}
+    observed: dict[tuple[str, str, str], dict[str, Any]] = {}
+    duplicate_keys: list[str] = []
+    observation_count = 0
+    route_results: list[dict[str, Any]] = []
     for item in observations if isinstance(observations, list) else []:
         if not isinstance(item, dict):
             continue
-        key = (str(item.get("surface") or ""), str(item.get("locale") or ""))
+        observation_count += 1
+        key = (str(item.get("surface") or ""), str(item.get("locale") or ""), str(item.get("route") or ""))
         if key in expected:
-            observed[key] = item
-    missing = sorted(f"{surface}/{locale}" for surface, locale in expected - observed.keys())
-    failed = sorted(f"{surface}/{locale}" for (surface, locale), item in observed.items() if item.get("passed") is not True or int(item.get("status", 200)) >= 400)
-    return {"schemaVersion": SCHEMA, "passed": not missing and not failed, "expectedPairs": sorted(f"{surface}/{locale}" for surface, locale in expected), "observedPairs": sorted(f"{surface}/{locale}" for surface, locale in observed), "missing": missing, "failed": failed}
+            if key in observed:
+                duplicate_keys.append(_key_text(key))
+            else:
+                observed[key] = item
+    missing = sorted(_key_text(key) for key in expected - observed.keys())
+    failed: list[str] = []
+    for key, item in observed.items():
+        surface = next(value for value in contract["surfaces"] if str(value["name"]) == key[0])
+        passed, missing_evidence = _route_result(item, list(surface["requiredEvidence"]), list(surface["requiredMetadata"]))
+        key_text = _key_text(key)
+        route_results.append({"route": key_text, "passed": passed, "missingEvidence": missing_evidence})
+        if not passed:
+            failed.append(key_text)
+    failed = sorted(set(failed))
+    return {
+        "schemaVersion": SCHEMA,
+        "passed": not missing and not failed and not duplicate_keys,
+        "expectedPairs": sorted(f"{surface}/{locale}" for surface, locale, _route in expected),
+        "expectedRoutes": sorted(_key_text(key) for key in expected),
+        "observedPairs": sorted(f"{surface}/{locale}" for surface, locale, _route in observed),
+        "observedRoutes": sorted(_key_text(key) for key in observed),
+        "observationCount": observation_count,
+        "duplicates": sorted(set(duplicate_keys)),
+        "missing": missing,
+        "failed": failed,
+        "routeResults": sorted(route_results, key=lambda value: value["route"]),
+    }

package/package.json

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

package/references/localization-extraction-render-prd.md

@@ -0,0 +1,55 @@
+# Localization source extraction and rendered validation
+
+## Problem
+
+`maggie-content-localization` currently accepts a prepared `content.json` and
+validates the resulting job. It does not extract translatable strings from a
+real project, so malformed JSX fragments, multiline text nodes, untranslated
+Latin terms, and script mismatches can pass the record validator while still
+breaking the rendered page.
+
+## Proposed stable workflow
+
+Add a read-only extractor and a separate rendered validation gate:
+
+```bash
+maggie localization extract --project . --source-dir src \
+  --routes-file docs/routes.tsv --output .maggie/localization/source.json
+maggie localization plan --content .maggie/localization/source.json ...
+maggie localization validate .maggie/localization/<job>.json \
+  --source .maggie/localization/source.json \
+  --render-report .maggie/localization/rendered.json
+```
+
+The extractor must use an AST-aware adapter for JSX/TSX/Astro/Vue/Svelte
+where available, with a conservative HTML fallback. It must never rewrite
+source files. Each extracted string records file, line, route, source hash,
+attribute/text-node kind, and an explicit translatable/non-translatable
+decision. Fragments containing braces or JavaScript operators are rejected or
+reported for review, not interpreted as text.
+
+The validation report must cover multiline nodes, required metadata, protected
+facts, script expectations, glossary/allowlist exceptions, and browser output.
+The rendered report must identify route, screenshot, console errors, failed
+asset requests, placeholder count, and untranslated required strings. Any
+failure keeps the locale non-indexable and blocks publish.
+
+## Acceptance criteria
+
+- JSX conditionals and expressions are never emitted as translation strings.
+- Text nodes spanning multiple lines are extracted and tested.
+- Script/Latin-word checks support all registered languages and configurable
+  proper-noun/glossary allowlists.
+- Source and translated strings are linked by stable IDs and source revision.
+- A clean extraction plus clean rendered report is required before approval;
+  record-only validation is not sufficient.
+- Unit fixtures cover Astro/JSX/Vue/Svelte/HTML, false positives, protected
+  facts, multiline nodes, script checks, and route-level browser errors.
+- The feature remains local-first, dependency-adaptable, redacted, and
+  backward-compatible with existing `content.json` input.
+
+## Out of scope
+
+Automatic translation quality scoring, silent source rewriting, and automatic
+publish. Translation generation and owner/Admin approval remain separate
+operations.