@topy-ai/maggie 0.7.17 → 0.7.18

package/README.md

@@ -88,6 +88,23 @@ hours. `maggie seo social-cards` checks per-page OG image dimensions and format;
 Dash inventory separates renderer kind from public page kind while reporting
 source coverage for code-rendered routes.
 
+Service booking providers can be checked with a machine-readable,
+fixture-backed capability matrix:
+
+```bash
+maggie service capability-audit --project . \
+  --catalogue .maggie/booking/services.json \
+  --capabilities-file .maggie/booking/provider-capabilities.json \
+  --fixture .maggie/booking/fixtures/provider.json
+```
+
+The declaration records variant mode (`native`, `derived-offers`,
+`single-fallback`, or `blocked`), price semantics, and stable-ID confidence.
+The audit also records observed counts and fixture evidence. Localized service
+variants use market/locale-aware canonical routes and reciprocal hreflang.
+Release preflight consumes the latest matching scenario QA run when one is
+configured and blocks incomplete evidence.
+
 For Google integrations, validate a redacted provider matrix before reporting
 access. The command fails closed on unknown scopes, missing Ads prerequisites,
 duplicate provider resources, and unverified edit/publish claims:
@@ -145,7 +162,7 @@ maggie memory ...                # confirmed preferences and lessons
 maggie feedback ...              # redact, preview, submit, list
 maggie qa ...                    # scenario browser QA, fix/retest, release gate
 maggie localization ...          # plan, validate, review, publish, stale
-maggie service ...               # import, sync, generate, validate
+maggie service ...               # import, sync, capability audit, validate
 maggie seo performance ...       # sampled PageSpeed/CWV report and baseline
 maggie seo images ...             # inventory, variants, confirmation, validate
 maggie seo sitemap ...            # typed/semantic plan, agent-files, apply, rollback
@@ -267,8 +284,8 @@ artifact schemas.
 Recommended upgrade sequence for the current release:
 
 ```bash
-npx @topy-ai/maggie@0.7.17 update --project . --force
-npx @topy-ai/maggie@0.7.17 cleanup --project .
+npx @topy-ai/maggie@0.7.18 update --project . --force
+npx @topy-ai/maggie@0.7.18 cleanup --project .
 ```
 
 Maintainers should pass npm credentials through the repository helper, never
@@ -278,7 +295,10 @@ as a command-line argument:
 node scripts/publish-npm.mjs --maggie-env-file ../.env
 ```
 
-The 0.7.17 workflow adds sanitized database-backed blog gate adapters, deployed
+The 0.7.18 workflow adds staged/untracked changed-surface detection, scenario
+QA release integration, market/locale-aware service variant routes and
+reciprocal hreflang, provider capability matrices with fixture evidence, and
+feedback fixed-proof/path-privacy gates. The 0.7.17 workflow adds sanitized database-backed blog gate adapters, deployed
 IndexNow key verification, social-card and cross-shell head-tag audits, required
 Open Graph image coverage, and behavioural favicon verification. The 0.7.16
 workflow tightens the review-gate exit code and adds retry-path regression

package/README.zh-TW.md

@@ -8,7 +8,7 @@ Codex、Claude Code 與相容的 coding agents。
 ## 安裝
 
 ```bash
-npx @topy-ai/maggie@0.7.16 init --agent all
+npx @topy-ai/maggie@0.7.18 init --agent all
 npx @topy-ai/maggie doctor --project .
 ```
 
@@ -25,7 +25,9 @@ maggie doctor --project . --require-bootstrap --strict
 deployment、memory、feedback 和 MaggieDash。內容先 draft/review，外部寫入、
 publish 與 production deployment 需要明確確認。
 
-0.7.16 補強 review gate 的 CI exit code 與 IndexNow retry regression；
+0.7.18 加入 staged/untracked changed-surface release gate、QA run 與 release
+整合、market/locale-aware service variant route、provider capability matrix
+fixture evidence，以及 feedback fixed-proof/path privacy gate。0.7.16 補強 review gate 的 CI exit code 與 IndexNow retry regression；
 0.7.15 也加入 API schema contract、blog review gate、sitemap freshness
 warning、change-driven IndexNow 與 page-kind/source-coverage inventory。
 
@@ -59,6 +61,12 @@ maggie migration identity --identity-file .maggie/db-identity.json \
 maggie qa start --project . --scenario-file .maggie/scenario-manifest.json \
   --environment local --base-url http://localhost:4321
 maggie qa summary --project . --run <run-id>
+
+# Provider variant capability matrix
+maggie service capability-audit --project . \
+  --catalogue .maggie/booking/services.json \
+  --capabilities-file .maggie/booking/provider-capabilities.json \
+  --fixture .maggie/booking/fixtures/provider.json
 ```
 
 完整中文說明、19 個 skills 清單和 roadmap：

package/bin/maggie.js

@@ -98,6 +98,7 @@ Usage:
   maggie service import <provider-url> --project PATH
   maggie service sync <provider-url> --project PATH
   maggie service generate --project PATH
+  maggie service capability-audit --project PATH --catalogue FILE --capabilities-file FILE --fixture FILE
   maggie service validate --project PATH
   maggie service inspect --project PATH
   maggie service status --project PATH

package/bundled-references/universal-booking-adapter.md

@@ -25,8 +25,10 @@ when a title changes.
     "title": "Signature Scalp Ritual",
     "description": "Provider-supplied factual description.",
     "category": {"level1": "Head Spa", "level2": "Scalp Treatments"},
-    "variants": [{
+  "variants": [{
       "id": "service-123:60",
+      "idSource": "provider",
+      "variantSource": "native",
       "title": "60 minutes",
       "durationMinutes": 60,
       "price": {"amountMinor": 9500, "currency": "GBP", "display": "£95.00"}
@@ -147,3 +149,36 @@ Provider adapters may add `raw` evidence in a private local snapshot, but
 public page generation consumes only the canonical fields above. A sync must
 preserve removed records as `archived` with `removedAt` and must output a
 change report.
+
+## Provider variant capability matrix
+
+Before service pages are published, each provider declares its variant
+behavior in a project-owned JSON file. The declaration is validated against a
+sanitized fixture and emits `maggie-provider-variant-capabilities.v1`:
+
+```json
+{
+  "schemaVersion": "maggie-provider-capabilities.v1",
+  "providers": [{
+    "provider": "fresha",
+    "variantMode": "native",
+    "priceSemantics": "minor-unit-and-display",
+    "stableIdConfidence": "high"
+  }]
+}
+```
+
+`variantMode` is one of `native`, `derived-offers`, `single-fallback`, or
+`blocked`. `priceSemantics` records whether structured minor units and display
+prices are available. `stableIdConfidence` must be justified by provider or
+derived ID evidence. The audit records service/variant counts, observed source
+types, fixture name and hash, and validation errors without copying fixture
+rows or provider credentials. Run it with:
+
+```bash
+maggie service capability-audit \
+  --project . \
+  --catalogue .maggie/booking/services.json \
+  --capabilities-file .maggie/booking/provider-capabilities.json \
+  --fixture .maggie/booking/fixtures/provider.json
+```

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

@@ -32,7 +32,8 @@ response bodies in it.
 
 When a release changes a visitor-facing HTML, CSS, component, or asset surface,
 the release preflight automatically requires both a passing icon inventory and
-rendered canary evidence. The canary must include screenshots, zero console or
+rendered canary evidence. It considers unstaged, staged, and untracked
+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.
 
@@ -161,6 +162,13 @@ python3 tools/clis/maggie_release.py /path/to/project \
   --base-url https://staging.example.com
 ```
 
+If `.maggie/scenario-manifest.json` or `.maggie/qa-runs/` exists, the same
+preflight consumes the latest matching `maggie qa` run for the requested
+environment (and `--base-url`, when supplied). It blocks when a scenario is
+not passed, has no browser-adapter evidence, or the matching run is missing.
+Projects without scenario QA report `not-configured`; Maggie does not run the
+browser itself.
+
 This aggregates deployment, migration, provider-health, schedule, analytics,
 service-fact, editorial approval, durable SEO/route/category evidence,
 MaggieDash schema compatibility, and live runtime security-header checks. It writes

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

@@ -34,6 +34,11 @@ The draft is written to `.maggie/feedback/`. It contains the Maggie version,
 skill, run ID, phase, error fingerprint, expected/actual result, reproduction
 steps, resolution, validation, and metadata-only screenshot references.
 
+If a draft is marked fixed with `--fixed` (or the supplied run report says
+`fixed`), both `--resolution` and `--validation` are required. Feedback text
+also scrubs common POSIX/home/temp and Windows absolute paths by default while
+preserving public URLs and route paths.
+
 ## Submit explicitly
 
 The CLI never submits automatically. After reviewing the draft:

package/bundled-skills/maggie-qa-workflow/SKILL.md

@@ -69,6 +69,11 @@ maggie qa record --project . --run local-qa-001 \
 the test failed, a fix. After a fix, retest the original scenario and at least
 one adjacent scenario affected by the same surface.
 
+A passing `test` or `retest` requires at least one `--evidence` reference from
+the host browser adapter. The adapter owns console, network, authentication,
+URL, viewport, and screenshot capture; this skill stores only a relative path,
+URL reference, and hash when a local file exists.
+
 ## Gate and release evidence
 
 The run gate is `fail` when any scenario fails, `blocked` when there is no
@@ -88,6 +93,12 @@ Before calling a release Pass, also run the relevant build, accessibility,
 SEO, media, API, and deployment-canary checks. A green build, HTTP 200, source
 class, or one guest smoke is not browser QA evidence.
 
+`maggie release` consumes the latest matching run from `.maggie/qa-runs/` when
+the project has a scenario manifest or QA run directory. A matching run must
+have a passed summary, passing scenarios, a passing final test/retest event,
+and browser evidence for every scenario. No manifest or run reports an
+explicit `not-configured` state.
+
 ## Privacy and feedback
 
 Do not put passwords, tokens, cookies, full private URLs, personal data,

package/bundled-skills/maggie-service-booking/SKILL.md

@@ -21,7 +21,8 @@ supporting relations for all suggested candidates. Inspect each service's
 `pages` after selection and validate the rendered links. The current selection
 path writes `canonical` for selected pages; multiple selections can violate
 the one-canonical invariant. Resolve roles and run validation before publishing.
-Variant role assignment and layout/URL conventions remain tracked in issue #27.
+Variant role assignment and layout/URL conventions are enforced by the shared
+market/locale route and reciprocal hreflang contract.
 
 ## Automatic memory hook
 
@@ -107,6 +108,14 @@ python3 tools/clis/maggie_service_booking.py category-audit \
   --project . --rendered-dir /tmp/category-rendered
 
 python3 tools/clis/maggie_service_booking.py category-context --project .
+
+# Declare provider behavior, then validate it against the imported catalogue
+# and a sanitized fixture before publishing service pages.
+python3 tools/clis/maggie_service_booking.py capability-audit \
+  --project . \
+  --catalogue .maggie/booking/services.json \
+  --capabilities-file .maggie/booking/provider-capabilities.json \
+  --fixture .maggie/booking/fixtures/provider.json
 ```
 
 `import` creates the first catalogue. `sync` compares the newly imported
@@ -265,6 +274,15 @@ amounts silently. Include `Service` and `Offer` JSON-LD only from validated
 catalogue fields. Do not emit `Review`, `AggregateRating`, or medical claims
 unless verified source data is present.
 
+Localized and market-specific variants use
+`/services/<market>/<locale>/<variant-slug>/` as their canonical route. A
+translation never reuses the source route. Published variants expose
+reciprocal hreflang links only to published counterparts. Before generation,
+each provider must declare `variantMode` (`native`, `derived-offers`,
+`single-fallback`, or `blocked`), `priceSemantics`, and `stableIdConfidence`
+in a machine-readable capability file. The capability audit requires a
+sanitized fixture and fails closed on missing or contradictory evidence.
+
 ## AI category/page copy contract
 
 Read [`references/ai-service-copy-contract.md`](../../references/ai-service-copy-contract.md)

package/bundled-tools/clis/maggie_feedback.py

@@ -20,6 +20,12 @@ 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,;]+")
+LOCAL_PATH_RE = re.compile(
+    r"(?<![A-Za-z0-9])(?:~/(?:[^\s,;:)\]}]+/)*[^\s,;:)\]}]+|"
+    r"/(?:home|Users|private|tmp|var|mnt|opt|root|srv|workspace|workspaces)(?:/[^\s,;:)\]}]+)+|"
+    r"[A-Za-z]:[\\/]+(?:[^\\/\s,;:)\]}]+[\\/]+)*[^\\/\s,;:)\]}]+|"
+    r"\\\\[^\\/\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]
@@ -30,7 +36,8 @@ def now() -> str:
 
 
 def safe_text(value: object) -> str:
-    return SECRET_RE.sub(r"\1[REDACTED]", str(value or "")).strip()
+    value = SECRET_RE.sub(r"\1[REDACTED]", str(value or ""))
+    return LOCAL_PATH_RE.sub("[LOCAL_PATH_REDACTED]", value).strip()
 
 
 def project_fingerprint(project: Path) -> str:
@@ -90,6 +97,11 @@ def collect(args: argparse.Namespace) -> int:
     skill = args.skill or report.get("skill") or report.get("workflow") or "unknown"
     run_id = args.run_id or report.get("runId") or report.get("jobId") or ""
     actual = args.actual or report.get("actual") or report.get("error") or report.get("message") or ""
+    fixed = bool(args.fixed or report.get("fixed") is True or report.get("status") == "fixed")
+    resolution = safe_text(args.resolution or report.get("resolution"))
+    validation = safe_text(args.validation or report.get("validation"))
+    if fixed and (not resolution or not validation):
+        raise ValueError("fixed feedback requires non-empty --resolution and --validation")
     context = {"projectFingerprint": project_fingerprint(project)}
     if args.allow_project_context and args.context_note:
         context["note"] = safe_text(args.context_note)
@@ -103,15 +115,15 @@ def collect(args: argparse.Namespace) -> int:
         "skill": skill,
         "runId": run_id,
         "phase": args.phase or report.get("phase") or "",
-        "status": report.get("status") or ("fixed" if args.fixed else "reported"),
+        "status": report.get("status") or ("fixed" if fixed else "reported"),
         "summary": safe_text(args.summary),
         "expected": safe_text(args.expected),
         "actual": safe_text(actual),
         "errorFingerprint": safe_text(args.error_fingerprint or report.get("errorFingerprint") or ""),
         "stepsToReproduce": [safe_text(step) for step in args.reproduce],
-        "fixed": bool(args.fixed),
-        "resolution": safe_text(args.resolution),
-        "validation": safe_text(args.validation),
+        "fixed": fixed,
+        "resolution": resolution,
+        "validation": validation,
         "attachments": [attachment(value) for value in args.screenshot],
         "environment": {"os": platform.system().lower(), "python": platform.python_version()},
         "privacy": {"secretsRedacted": True, "projectContextAllowed": bool(args.allow_project_context)},

package/bundled-tools/clis/maggie_qa_workflow.py

@@ -224,6 +224,8 @@ def record(args: argparse.Namespace) -> int:
         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")
+    if phase in {"test", "retest"} and args.status == "pass" and not args.evidence:
+        raise ValueError("a passing test requires --evidence from the browser adapter")
     event = {
         "at": now(),
         "phase": phase,

package/bundled-tools/clis/maggie_release.py

@@ -16,7 +16,7 @@ from urllib.error import HTTPError, URLError
 from urllib.request import Request, urlopen
 from datetime import datetime, timezone
 from pathlib import Path
-from urllib.parse import urljoin
+from urllib.parse import urljoin, urlsplit
 
 
 ROOT = Path(__file__).resolve().parent
@@ -130,14 +130,23 @@ def evidence_gate(project: Path, environment: str) -> dict:
 def changed_surface_gate(project: Path) -> dict:
     """Require visual/runtime evidence when a visitor-facing surface changed."""
     try:
-        changed = subprocess.run(
+        changed_output = subprocess.run(
             ["git", "-C", str(project), "diff", "--name-only"],
             capture_output=True, text=True, check=True,
         ).stdout.splitlines()
+        staged_output = subprocess.run(
+            ["git", "-C", str(project), "diff", "--cached", "--name-only"],
+            capture_output=True, text=True, check=True,
+        ).stdout.splitlines()
+        untracked_output = subprocess.run(
+            ["git", "-C", str(project), "ls-files", "--others", "--exclude-standard", "-z"],
+            capture_output=True, text=True, check=True,
+        ).stdout.split("\0")
     except (OSError, subprocess.CalledProcessError):
         return {"name": "changed-surface-evidence", "passed": True, "exitCode": 0,
                 "result": {"passed": True, "changed": False, "reason": "project is not a git worktree"}, "stderr": ""}
     visitor_suffixes = {".astro", ".css", ".scss", ".html", ".jsx", ".tsx", ".js", ".ts", ".svg", ".png", ".jpg", ".jpeg", ".webp"}
+    changed = set(changed_output) | set(staged_output) | {path for path in untracked_output if path}
     surfaces = sorted(path for path in changed if Path(path).suffix.lower() in visitor_suffixes)
     if not surfaces:
         return {"name": "changed-surface-evidence", "passed": True, "exitCode": 0,
@@ -181,6 +190,82 @@ def changed_surface_gate(project: Path) -> dict:
             "result": {"passed": not errors, "changed": True, "surfaces": surfaces, "evidence": evidence, "errors": errors}, "stderr": ""}
 
 
+def _origin(value: object) -> str:
+    try:
+        parsed = urlsplit(str(value or ""))
+        if parsed.scheme and parsed.netloc:
+            return f"{parsed.scheme.lower()}://{parsed.netloc.lower()}"
+    except ValueError:
+        pass
+    return ""
+
+
+def _qa_run_matches(run: dict, manifest_label: str | None, environment: str, base_url: str | None) -> bool:
+    if run.get("schemaVersion") != "maggie.qa-run.v1":
+        return False
+    if run.get("environment") != environment:
+        return False
+    if manifest_label and run.get("scenarioManifest") != manifest_label:
+        return False
+    if base_url and _origin(run.get("baseUrl")) != _origin(base_url):
+        return False
+    return isinstance(run.get("scenarios"), dict) and bool(run.get("scenarios"))
+
+
+def qa_gate(project: Path, environment: str, base_url: str | None = None) -> dict:
+    """Consume the latest matching project QA run without running a browser."""
+    manifest = project / ".maggie" / "scenario-manifest.json"
+    run_dir = project / ".maggie" / "qa-runs"
+    run_paths = sorted(run_dir.glob("*.json")) if run_dir.is_dir() else []
+    configured = manifest.is_file() or bool(run_paths)
+    if not configured:
+        return {"name": "scenario-qa", "passed": True, "exitCode": 0,
+                "result": {"passed": True, "state": "not-configured", "configured": False,
+                            "reason": "no scenario manifest or QA run directory"}, "stderr": ""}
+
+    try:
+        manifest_label = str(manifest.relative_to(project)) if manifest.is_file() else None
+    except ValueError:
+        manifest_label = manifest.name if manifest.is_file() else None
+    candidates: list[tuple[Path, dict]] = []
+    invalid_count = 0
+    for path in run_paths:
+        try:
+            value = json.loads(path.read_text(encoding="utf-8"))
+            if isinstance(value, dict) and _qa_run_matches(value, manifest_label, environment, base_url):
+                candidates.append((path, value))
+        except (OSError, json.JSONDecodeError):
+            invalid_count += 1
+    if not candidates:
+        return {"name": "scenario-qa", "passed": False, "exitCode": 1,
+                "result": {"passed": False, "state": "inconclusive", "configured": True,
+                            "errors": ["no matching scenario QA run", f"invalidRuns={invalid_count}"]}, "stderr": ""}
+
+    path, run = max(candidates, key=lambda item: str(item[1].get("updatedAt") or item[1].get("createdAt") or ""))
+    errors: list[str] = []
+    summary = run.get("summary") if isinstance(run.get("summary"), dict) else {}
+    if summary.get("gate") != "pass":
+        errors.append("latest matching QA run is not passed")
+    for scenario in run.get("scenarios", {}).values():
+        if not isinstance(scenario, dict) or scenario.get("status") != "pass":
+            errors.append("latest matching QA run contains a non-passing scenario")
+            continue
+        history = scenario.get("history") if isinstance(scenario.get("history"), list) else []
+        last = history[-1] if history else {}
+        if last.get("phase") not in {"test", "retest"} or last.get("status") != "pass":
+            errors.append("latest matching QA run has a scenario without a passing final test")
+        if not isinstance(last.get("evidence"), list) or not last.get("evidence"):
+            errors.append("latest matching QA run has a scenario without browser evidence")
+    passed = not errors
+    try:
+        report_path = str(path.relative_to(project))
+    except ValueError:
+        report_path = path.name
+    return {"name": "scenario-qa", "passed": passed, "exitCode": 0 if passed else 1,
+            "result": {"passed": passed, "state": "passed" if passed else "failed", "configured": True,
+                        "run": report_path, "updatedAt": run.get("updatedAt"), "errors": errors}, "stderr": ""}
+
+
 def editorial_gate(project: Path) -> dict:
     """Require explicit editorial approval for every launch category.
 
@@ -279,6 +364,7 @@ def main() -> int:
 
     gates = []
     gates.append(changed_surface_gate(project))
+    gates.append(qa_gate(project, args.environment, args.base_url))
     gates.append(build_gate(project))
     for name, command in build_gates(project, args.environment, args.target, not args.skip_compatibility):
         gates.append(run_gate(name, command, project))

package/bundled-tools/clis/maggie_service_booking.py

@@ -12,6 +12,7 @@ from urllib.request import Request, urlopen
 
 sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "runtime"))
 from route_imports import imported_components  # noqa: E402
+from booking_capabilities import audit_matrix  # noqa: E402
 
 NOW = lambda: datetime.now(timezone.utc).isoformat()
 MONEY = re.compile(r"(?:£|GBP\s*)\s*([0-9]+(?:[.,][0-9]{1,2})?)", re.I)
@@ -76,7 +77,8 @@ def parse(source, provider):
                 currency=(offer.get("priceCurrency") or ("GBP" if price and ("£" in text or provider=="fresha") else None))
                 if price is None and dm is None: continue
                 amount=int(round(float(str(price).replace(",",""))*100)) if price is not None else None
-                variants.append({"id":f"{slug(name)}:{dm.group(1) if dm else 'default'}","title":offer.get("name") or (f"{dm.group(1)} minutes" if dm else "Standard"),"durationMinutes":int(dm.group(1)) if dm else None,"price":{"amountMinor":amount,"currency":currency,"display":f"£{amount/100:.2f}" if amount is not None and currency=="GBP" else None}})
+                provider_variant_id = offer.get("sku") or offer.get("@id") or offer.get("id")
+                variants.append({"id":str(provider_variant_id or f"{slug(name)}:{dm.group(1) if dm else 'default'}"),"idSource":"provider" if provider_variant_id else "derived","variantSource":"native" if provider_variant_id else "derived-offers","title":offer.get("name") or (f"{dm.group(1)} minutes" if dm else "Standard"),"durationMinutes":int(dm.group(1)) if dm else None,"price":{"amountMinor":amount,"currency":currency,"display":f"£{amount/100:.2f}" if amount is not None and currency=="GBP" else None}})
             url=item.get("url") or item.get("sameAs")
             if not variants and not url: continue
             pid=str(item.get("providerServiceId") or item.get("productID") or item.get("sku") or slug(name))
@@ -113,7 +115,8 @@ def parse_fresha_embedded(raw, source):
                     parsed_amount, parsed_currency=money_value(display or "")
                     caption=variant.get("caption") or ""
                     duration=duration_minutes(caption) or round(float(variant.get("maxInSeconds") or variant.get("minInSeconds") or item.get("maxInSeconds") or item.get("minInSeconds") or 0)/60) or None
-                    variants.append({"id":str(variant.get("id") or f'{item["serviceId"]}:default'),"title":variant.get("name") or caption or "Standard","durationMinutes":duration,"price":{"amountMinor":parsed_amount if parsed_amount is not None else amount,"currency":parsed_currency or currency,"display":display}})
+                    provider_variant_id = variant.get("id")
+                    variants.append({"id":str(provider_variant_id or f'{item["serviceId"]}:default'),"idSource":"provider" if provider_variant_id else "derived","variantSource":"native" if provider_variant_id else "single-fallback","title":variant.get("name") or caption or "Standard","durationMinutes":duration,"price":{"amountMinor":parsed_amount if parsed_amount is not None else amount,"currency":parsed_currency or currency,"display":display}})
                 if not variants: continue
                 booking=item.get("bookingUrl") or f'{source.split("?")[0]}/booking?offerItemId={quote(str(item.get("id") or ""))}'
                 record=make_record("fresha",source,str(item["serviceId"]),str(item["name"]),str(item.get("description") or ""),variants,booking,[])
@@ -157,7 +160,7 @@ def parse_fresha_embedded(raw, source):
         for caption, display, vid, vname in variant_pattern.findall(match.group("variants")):
             duration=duration_minutes(caption)
             amount, currency=money_value(display)
-            variants.append({"id":vid,"title":vname or caption,"durationMinutes":duration,"price":{"amountMinor":amount,"currency":currency,"display":display}})
+            variants.append({"id":vid,"idSource":"provider","variantSource":"native","title":vname or caption,"durationMinutes":duration,"price":{"amountMinor":amount,"currency":currency,"display":display}})
         if not variants: continue
         name=variants[0]["title"]
         records.append(make_record("fresha",source,match.group("pid"),name,description,variants,None,[]))
@@ -436,6 +439,40 @@ def cmd_category_hash(args):
     print(json.dumps(report, indent=2, ensure_ascii=False))
     return 0 if not errors else 1
 
+
+def cmd_capability_audit(args):
+    """Validate provider declarations and emit a fixture-backed capability matrix."""
+    project = root(args)
+    def read(path_value):
+        path_value = Path(path_value)
+        path_value = path_value if path_value.is_absolute() else project / path_value
+        return path_value.resolve(), json.loads(path_value.resolve().read_text(encoding="utf-8"))
+    try:
+        catalogue_path, catalogue = read(args.catalogue)
+        declaration_path, declarations = read(args.capabilities_file)
+        fixture = None
+        fixture_path = None
+        fixture_digest = None
+        if args.fixture:
+            fixture_path, fixture = read(args.fixture)
+            fixture_digest = hashlib.sha256(fixture_path.read_bytes()).hexdigest()
+        result = audit_matrix(declarations, catalogue, provider=args.provider, fixture=fixture,
+                              fixture_name=fixture_path.name if fixture_path else None,
+                              fixture_sha256=fixture_digest)
+    except (OSError, ValueError, json.JSONDecodeError) as error:
+        print(json.dumps({"schemaVersion": "maggie-provider-variant-capabilities.v1", "passed": False, "errors": [str(error)]}, indent=2))
+        return 1
+    output = Path(args.output) if args.output else project / "docs" / "provider-variant-capabilities.json"
+    if not output.is_absolute():
+        output = project / output
+    output = output.resolve()
+    output.parent.mkdir(parents=True, exist_ok=True)
+    result["catalogue"] = catalogue_path.name
+    result["declarations"] = declaration_path.name
+    output.write_text(json.dumps(result, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+    print(json.dumps({"status": "passed" if result["passed"] else "failed", "report": str(output), "providers": len(result["providers"]), "errors": result["errors"]}, indent=2, ensure_ascii=False))
+    return 0 if result["passed"] else 1
+
 def category_audit_report(project, pages_dir, copy_data, rendered_dir=None, environment="staging"):
     errors = []
     copy_path = (project / copy_data).resolve()
@@ -976,6 +1013,7 @@ def main():
     q=sub.add_parser("category-editorial-review"); q.add_argument("--project",default="."); q.add_argument("--copy-data",default="docs/category-page-copy.json"); q.add_argument("--category",action="append",help="category to review; defaults to all seven launch categories"); q.add_argument("--reviewer"); q.add_argument("--evidence",action="append",default=[],help="review evidence path or URL; repeatable"); q.add_argument("--apply",action="store_true",help="write explicit editorial approval metadata"); q.add_argument("--confirm",action="store_true",help="confirm that the selected records were actually reviewed by a human")
     q=sub.add_parser("category-hash"); q.add_argument("--project",default="."); q.add_argument("--copy-data",required=True); q.add_argument("--apply",action="store_true",help="backfill deterministic provenance hashes in this generated artifact")
     q=sub.add_parser("fact-audit"); q.add_argument("--project",default="."); q.add_argument("--backfill-source",action="store_true",help="copy the catalogue sourceUrl into records that have no sourceUrl"); q.add_argument("--overrides",help="JSON of human-approved, evidenced descriptions for provider gaps"); q.add_argument("--apply-overrides",action="store_true",help="apply only approved fact overrides to the draft catalogue")
+    q=sub.add_parser("capability-audit", help="validate provider variant declarations and fixture evidence"); q.add_argument("--project",default="."); q.add_argument("--provider"); q.add_argument("--catalogue",default=".maggie/booking/services.json"); q.add_argument("--capabilities-file",default=".maggie/booking/provider-capabilities.json"); q.add_argument("--fixture",help="sanitized provider fixture JSON"); q.add_argument("--output")
     q=sub.add_parser("category-context"); q.add_argument("--project",default="."); q.add_argument("--output")
     q=sub.add_parser("validate-copy"); q.add_argument("--project",default="."); q.add_argument("--service-id",required=True); q.add_argument("--copy-data",required=True,help="AI-authored service copy JSON")
     q=sub.add_parser("sitemap-audit"); q.add_argument("--project",default="."); q.add_argument("--index",required=True,help="rendered sitemap index XML"); q.add_argument("--sitemap-dir",required=True,help="directory containing rendered child sitemap XML files"); q.add_argument("--base-url",help="reserved for URL evidence and report context"); q.add_argument("--environment",choices=("development","staging","production"),default="staging")
@@ -997,6 +1035,7 @@ def main():
     if a.command=="category-editorial-review": return cmd_category_editorial_review(a)
     if a.command=="category-hash": return cmd_category_hash(a)
     if a.command=="fact-audit": return cmd_fact_audit(a)
+    if a.command=="capability-audit": return cmd_capability_audit(a)
     if a.command=="category-context": return cmd_category_context(a)
     if a.command=="validate-copy": return cmd_validate_copy(a)
     if a.command=="sitemap-audit": return cmd_sitemap_audit(a)

package/bundled-tools/runtime/booking_capabilities.py

@@ -0,0 +1,137 @@
+"""Provider-neutral service variant capability matrix validation."""
+from __future__ import annotations
+
+from collections import Counter
+from typing import Any
+
+SCHEMA_VERSION = "maggie-provider-variant-capabilities.v1"
+VARIANT_MODES = {"native", "derived-offers", "single-fallback", "blocked"}
+PRICE_SEMANTICS = {"minor-unit", "minor-unit-and-display", "display-only", "unavailable", "unknown"}
+STABLE_ID_CONFIDENCE = {"high", "medium", "low", "unknown", "blocked"}
+
+
+def _services(value: object) -> list[dict[str, Any]]:
+    if isinstance(value, dict) and isinstance(value.get("services"), list):
+        return [item for item in value["services"] if isinstance(item, dict)]
+    if isinstance(value, list):
+        return [item for item in value if isinstance(item, dict)]
+    return []
+
+
+def _fixture_evidence(fixture: object | None, name: str | None, digest: str | None) -> dict[str, Any]:
+    services = _services(fixture)
+    variants = [variant for service in services for variant in _services({"services": service.get("variants", [])})]
+    return {
+        "provided": fixture is not None,
+        "name": name or None,
+        "sha256": digest or None,
+        "serviceCount": len(services),
+        "variantCounts": [len(service.get("variants") or []) for service in services],
+        "allVariantIdsPresent": bool(variants) and all(str(item.get("id") or "").strip() for item in variants),
+        "allVariantSourcesPresent": bool(variants) and all(str(item.get("variantSource") or "").strip() for item in variants),
+    }
+
+
+def audit_provider(declaration: object, catalogue: object, *, fixture: object | None = None,
+                   fixture_name: str | None = None, fixture_sha256: str | None = None) -> dict[str, Any]:
+    """Validate one provider declaration against catalogue and fixture evidence."""
+    item = declaration if isinstance(declaration, dict) else {}
+    provider = str(item.get("provider") or "").strip()
+    mode = str(item.get("variantMode") or "").strip()
+    price_semantics = str(item.get("priceSemantics") or "").strip()
+    stable_id_confidence = str(item.get("stableIdConfidence") or "").strip()
+    errors: list[str] = []
+    if not provider:
+        errors.append("provider is required")
+    if mode not in VARIANT_MODES:
+        errors.append("variantMode must be native, derived-offers, single-fallback, or blocked")
+    if price_semantics not in PRICE_SEMANTICS:
+        errors.append("priceSemantics is unsupported")
+    if stable_id_confidence not in STABLE_ID_CONFIDENCE:
+        errors.append("stableIdConfidence is unsupported")
+
+    services = _services(catalogue)
+    active_services = [service for service in services if service.get("status", "active") != "archived"]
+    variants = [variant for service in active_services for variant in (service.get("variants") or []) if isinstance(variant, dict)]
+    observed_modes = Counter(str(variant.get("variantSource") or "unknown") for variant in variants)
+    all_ids = bool(variants) and all(str(variant.get("id") or "").strip() for variant in variants)
+    native_id_sources = all(str(variant.get("idSource") or "") in {"provider", "native"} for variant in variants) if variants else False
+    structured_prices = bool(variants) and all(
+        isinstance(variant.get("price"), dict)
+        and isinstance(variant["price"].get("amountMinor"), int)
+        and str(variant["price"].get("currency") or "").isalpha()
+        for variant in variants
+    )
+    if not services:
+        errors.append("catalogue has no services")
+    if mode != "blocked" and not variants:
+        errors.append("declared non-blocked provider has no active variants")
+    if mode == "native" and variants and not native_id_sources:
+        errors.append("native variants require provider/native idSource evidence")
+    if mode == "single-fallback" and any(len(service.get("variants") or []) > 1 for service in active_services):
+        errors.append("single-fallback provider has a service with multiple variants")
+    expected_source = {"native": "native", "derived-offers": "derived-offers", "single-fallback": "single-fallback"}.get(mode)
+    if expected_source and variants and any(source != expected_source for source in observed_modes):
+        errors.append(f"catalogue variantSource does not match declared {mode} mode")
+    if stable_id_confidence == "high" and not native_id_sources:
+        errors.append("high stable-ID confidence requires provider/native idSource evidence")
+    if fixture is None:
+        errors.append("fixture evidence is required")
+
+    evidence = _fixture_evidence(fixture, fixture_name, fixture_sha256)
+    if fixture is not None and evidence["serviceCount"] == 0:
+        errors.append("fixture evidence has no services")
+    if mode != "blocked" and fixture is not None and not evidence["allVariantIdsPresent"]:
+        errors.append("fixture evidence is missing variant IDs")
+    if mode != "blocked" and fixture is not None and not evidence["allVariantSourcesPresent"]:
+        errors.append("fixture evidence is missing variant sources")
+    if price_semantics in {"minor-unit", "minor-unit-and-display"} and variants and not structured_prices:
+        errors.append("declared minor-unit price semantics require amountMinor and currency")
+    if price_semantics == "display-only" and variants and any(
+        isinstance(variant.get("price"), dict) and variant["price"].get("amountMinor") is not None
+        for variant in variants
+    ):
+        errors.append("display-only price semantics cannot contain amountMinor")
+    if price_semantics == "unavailable" and variants and any(variant.get("price") for variant in variants):
+        errors.append("unavailable price semantics cannot contain price data")
+    if provider and isinstance(catalogue, dict) and catalogue.get("provider") and catalogue.get("provider") != provider:
+        errors.append("catalogue provider does not match declaration")
+
+    passed = not errors
+    return {
+        "provider": provider or None,
+        "variantMode": mode or None,
+        "priceSemantics": price_semantics or None,
+        "stableIdConfidence": stable_id_confidence or None,
+        "observed": {
+            "serviceCount": len(services),
+            "activeServiceCount": len(active_services),
+            "variantCount": len(variants),
+            "variantSources": dict(sorted(observed_modes.items())),
+            "allVariantIdsPresent": all_ids,
+            "allStructuredPrices": structured_prices,
+        },
+        "fixtureEvidence": evidence,
+        "passed": passed,
+        "errors": errors,
+    }
+
+
+def audit_matrix(declarations: object, catalogue: object, *, provider: str | None = None,
+                 fixture: object | None = None, fixture_name: str | None = None,
+                 fixture_sha256: str | None = None) -> dict[str, Any]:
+    """Validate a machine-readable provider declaration file."""
+    if isinstance(declarations, dict) and declarations.get("providers"):
+        entries = declarations["providers"]
+    elif isinstance(declarations, list):
+        entries = declarations
+    else:
+        entries = []
+    if not isinstance(entries, list):
+        entries = []
+    selected = [entry for entry in entries if isinstance(entry, dict) and (not provider or entry.get("provider") == provider)]
+    if not selected:
+        return {"schemaVersion": SCHEMA_VERSION, "passed": False, "providers": [], "errors": ["no provider declaration selected"]}
+    results = [audit_provider(entry, catalogue, fixture=fixture, fixture_name=fixture_name, fixture_sha256=fixture_sha256) for entry in selected]
+    return {"schemaVersion": SCHEMA_VERSION, "passed": all(result["passed"] for result in results), "providers": results,
+            "errors": [f"{result.get('provider') or 'unknown'}: {error}" for result in results for error in result["errors"]]}

package/bundled-tools/runtime/service_variants.py

@@ -35,6 +35,16 @@ def variant_slug(kind: str, *, location: str = "", event: str = "", holiday: str
     return f"{kind}/{slug_part(value)}"
 
 
+def locale_segment(value: str) -> str:
+    """Return the stable lowercase URL segment for a BCP 47-like locale."""
+    return slug_part(value.replace("_", "-"))
+
+
+def variant_canonical_url(slug: str, locale: str, market: str) -> str:
+    """Build a collision-safe, market/language-aware service URL."""
+    return f"/services/{slug_part(market)}/{locale_segment(locale)}/{slug.strip('/')}/"
+
+
 def similarity(source: str, variant: str) -> float:
     left, right = set(re.findall(r"[a-z0-9]+", source.lower())), set(re.findall(r"[a-z0-9]+", variant.lower()))
     return 1.0 if not left and not right else len(left & right) / max(1, len(left | right))
@@ -62,6 +72,20 @@ class ServiceVariantStore:
             raise ValueError("service variant not found")
         return found
 
+    def _cluster(self, canonical_variant_id: str) -> list[dict]:
+        return [
+            item for item in self.data["variants"]
+            if item.get("id") == canonical_variant_id or item.get("canonicalVariantId") == canonical_variant_id
+        ]
+
+    def _refresh_hreflang(self, canonical_variant_id: str) -> None:
+        """Keep published locale links reciprocal and limited to published peers."""
+        cluster = self._cluster(canonical_variant_id)
+        published = [item for item in cluster if item.get("status") == "published"]
+        published_links = {item["locale"]: item["canonicalUrl"] for item in published}
+        for item in cluster:
+            item["hreflang"] = published_links if item in published else {item["locale"]: item["canonicalUrl"]}
+
     def create(self, *, service_id: str, variant_id: str, variant_type: str, locale: str, market: str,
                slug: str, title: str, facts: list[dict], source_revision: str, canonical_variant_id: str | None = None,
                cluster_links: list[str] | None = None, layout_family: str = "service-default", actor: str = "cli") -> dict:
@@ -73,15 +97,19 @@ class ServiceVariantStore:
             raise ValueError("variant requires meaningful keyed facts")
         if any(item["id"] == variant_id for item in self.data["variants"]):
             raise ValueError("variant ID already exists")
-        if any(item["slug"] == slug and item["locale"] == locale for item in self.data["variants"]):
-            raise ValueError("variant slug and locale collision")
         if canonical_variant_id and not any(item["id"] == canonical_variant_id for item in self.data["variants"]):
             raise ValueError("canonical variant does not exist")
+        canonical_url = variant_canonical_url(slug, locale, market)
+        if any(item.get("canonicalUrl") == canonical_url for item in self.data["variants"]):
+            raise ValueError("variant market, locale and slug route collision")
+        family = canonical_variant_id or variant_id
+        if any(item.get("canonicalVariantId") == family and item.get("locale") == locale for item in self.data["variants"]):
+            raise ValueError("variant locale collision in translation cluster")
         item = {"id": variant_id, "serviceId": service_id, "variantType": variant_type, "locale": locale,
                 "market": market, "slug": slug, "title": title, "facts": facts,
                 "clusterLinks": sorted(set(cluster_links or [])), "layoutFamily": layout_family,
-                "canonicalVariantId": canonical_variant_id or variant_id, "canonicalUrl": "/services/" + slug + "/",
-                "hreflang": {locale: "/services/" + slug + "/"}, "sourceRevision": source_revision,
+                "canonicalVariantId": family, "canonicalUrl": canonical_url,
+                "hreflang": {locale: canonical_url}, "sourceRevision": source_revision,
                 "provenance": {"operation": "create", "actor": actor, "sourceRevision": source_revision},
                 "status": "draft", "createdAt": now(), "updatedAt": now()}
         self.data["variants"].append(item); self._event("variant.created", variant_id, actor, "draft created"); self._save()
@@ -120,6 +148,7 @@ class ServiceVariantStore:
                 raise ValueError("canonical source must be published before a translated variant")
         old = item["status"]; item["status"] = target; item["updatedAt"] = now()
         item.setdefault("approval", []).append({"from": old, "to": target, "actor": actor, "reason": reason, "at": now()})
+        self._refresh_hreflang(item["canonicalVariantId"])
         self._event("variant." + target, variant_id, actor, reason); self._save(); return item
 
     def plan_slug_change(self, variant_id: str, new_slug: str, actor: str) -> dict:
@@ -128,17 +157,29 @@ class ServiceVariantStore:
             raise ValueError("published URL changes require owner approval")
         if not new_slug.startswith(item["variantType"] + "/") or not SLUG_WORD.fullmatch(new_slug.split("/", 1)[-1]):
             raise ValueError("new slug violates variant grammar")
-        if any(v["slug"] == new_slug and v["locale"] == item["locale"] for v in self.data["variants"] if v["id"] != variant_id):
-            raise ValueError("new slug collides with another variant")
-        redirect = {"from": item["canonicalUrl"], "to": "/services/" + new_slug + "/", "ownerApproval": actor, "status": "planned"}
+        new_url = variant_canonical_url(new_slug, item["locale"], item["market"])
+        if any(v.get("canonicalUrl") == new_url for v in self.data["variants"] if v["id"] != variant_id):
+            raise ValueError("new market, locale and slug route collides with another variant")
+        redirect = {"from": item["canonicalUrl"], "to": new_url, "ownerApproval": actor, "status": "planned"}
         self.data["redirects"].append(redirect); self._save(); return redirect
 
     def validate(self, variant_id: str, source_text: str | None = None, render_report: dict | None = None) -> dict:
         item = self._find(variant_id); errors = []
+        expected_url = variant_canonical_url(item["slug"], item["locale"], item["market"])
+        if item.get("canonicalUrl") != expected_url:
+            errors.append("canonical URL must include market, locale and variant slug")
         if not item["clusterLinks"] and item["variantType"] != "location": errors.append("cluster links required")
         if source_text is not None and similarity(source_text, item["title"] + " " + " ".join(str(f["value"]) for f in item["facts"])) < 0.1:
             errors.append("variant content has no meaningful similarity to source")
         if item["canonicalVariantId"] != item["id"] and item["canonicalVariantId"] not in {v["id"] for v in self.data["variants"]}: errors.append("canonical relation missing")
+        if item.get("status") == "published":
+            expected_hreflang = {
+                peer["locale"]: peer["canonicalUrl"]
+                for peer in self._cluster(item["canonicalVariantId"])
+                if peer.get("status") == "published"
+            }
+            if item.get("hreflang") != expected_hreflang:
+                errors.append("published hreflang links must be reciprocal published counterparts")
         if render_report is not None:
             if render_report.get("schemaVersion") != "maggie-service-variant-render.v1" or render_report.get("passed") is not True:
                 errors.append("render report is not passed")

package/package.json

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

package/references/universal-booking-adapter.md

@@ -25,8 +25,10 @@ when a title changes.
     "title": "Signature Scalp Ritual",
     "description": "Provider-supplied factual description.",
     "category": {"level1": "Head Spa", "level2": "Scalp Treatments"},
-    "variants": [{
+  "variants": [{
       "id": "service-123:60",
+      "idSource": "provider",
+      "variantSource": "native",
       "title": "60 minutes",
       "durationMinutes": 60,
       "price": {"amountMinor": 9500, "currency": "GBP", "display": "£95.00"}
@@ -147,3 +149,36 @@ Provider adapters may add `raw` evidence in a private local snapshot, but
 public page generation consumes only the canonical fields above. A sync must
 preserve removed records as `archived` with `removedAt` and must output a
 change report.
+
+## Provider variant capability matrix
+
+Before service pages are published, each provider declares its variant
+behavior in a project-owned JSON file. The declaration is validated against a
+sanitized fixture and emits `maggie-provider-variant-capabilities.v1`:
+
+```json
+{
+  "schemaVersion": "maggie-provider-capabilities.v1",
+  "providers": [{
+    "provider": "fresha",
+    "variantMode": "native",
+    "priceSemantics": "minor-unit-and-display",
+    "stableIdConfidence": "high"
+  }]
+}
+```
+
+`variantMode` is one of `native`, `derived-offers`, `single-fallback`, or
+`blocked`. `priceSemantics` records whether structured minor units and display
+prices are available. `stableIdConfidence` must be justified by provider or
+derived ID evidence. The audit records service/variant counts, observed source
+types, fixture name and hash, and validation errors without copying fixture
+rows or provider credentials. Run it with:
+
+```bash
+maggie service capability-audit \
+  --project . \
+  --catalogue .maggie/booking/services.json \
+  --capabilities-file .maggie/booking/provider-capabilities.json \
+  --fixture .maggie/booking/fixtures/provider.json
+```