@topy-ai/maggie 0.7.21 → 0.7.23

package/README.md

@@ -76,6 +76,19 @@ maggie qa summary --project . --run <run-id>
 The QA workflow stores secret-free run state under `.maggie/qa-runs/` and
 keeps project-specific scenarios and evidence outside the npm package.
 
+Before recording a passing user-facing assertion, lint it against runtime
+evidence; source-only class or markup checks are rejected:
+
+```bash
+maggie qa assertion-audit --project . \
+  --assertions .maggie/qa-assertions.json \
+  --output docs/qa-assertion-audit.json
+```
+
+For a dialog or drawer, include a browser-runtime `scroll-owner-count` check
+with `expected: 1`. This catches the fixed-shell plus inner-content double
+scrollbar that static class checks can miss.
+
 Dashboard and documentation audits are provider-neutral and keep host data
 behind explicit evidence files:
 
@@ -123,6 +136,24 @@ 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.
 
+The provider-owned parser also supports safe catalogue and lifecycle review:
+
+```bash
+maggie service catalogue-check "<provider-location-url>" \
+  --treatment "Lymphatic drainage massage"
+maggie service sync-report --project .
+maggie service retirement-audit --project . \
+  --catalogue .maggie/booking/services.json \
+  --evidence .maggie/booking/retirement-evidence.json
+```
+
+`catalogue-check` avoids marketplace noise when the provider exposes an
+authoritative embedded catalogue. `sync-report` shows field and variant
+before/after changes. `retirement-audit` validates sanitized runtime evidence
+for `pending`, `redirect`, `tombstone`, or `gone` endings, including HTTP
+status, booking suppression, noindex/unavailable signals, and sitemap
+exclusion. Response bodies are never stored.
+
 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:
@@ -183,7 +214,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, capability audit, validate
+maggie service ...               # import, sync/report, catalogue, lifecycle, 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
@@ -325,8 +356,8 @@ artifact schemas.
 Recommended upgrade sequence for the current release:
 
 ```bash
-npx @topy-ai/maggie@0.7.21 update --project . --force
-npx @topy-ai/maggie@0.7.21 cleanup --project .
+npx @topy-ai/maggie@0.7.23 update --project . --force
+npx @topy-ai/maggie@0.7.23 cleanup --project .
 ```
 
 Maintainers should pass npm credentials through the repository helper, never
@@ -336,6 +367,12 @@ as a command-line argument:
 node scripts/publish-npm.mjs --maggie-env-file ../.env
 ```
 
+The 0.7.23 workflow adds the single-scroll-owner MaggieDash modal primitive,
+server-runtime-only auth/provider configuration guidance, best-effort optional
+identity-mirror semantics, and `scroll-owner-count` browser QA evidence. The
+0.7.22 workflow adds provider-catalogue authority checks, field/variant
+sync reports, separate supply/display states, site-owned slug proposals,
+withdrawal endings, retirement evidence audits, and runtime QA assertion lint.
 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

package/README.zh-TW.md

@@ -8,7 +8,7 @@ Codex、Claude Code 與相容的 coding agents。
 ## 安裝
 
 ```bash
-npx @topy-ai/maggie@0.7.21 init --agent all
+npx @topy-ai/maggie@0.7.23 init --agent all
 npx @topy-ai/maggie doctor --project .
 ```
 
@@ -25,6 +25,11 @@ maggie doctor --project . --require-bootstrap --strict
 deployment、memory、feedback 和 MaggieDash。內容先 draft/review，外部寫入、
 publish 與 production deployment 需要明確確認。
 
+0.7.23 加入 dashboard dialog 單一 scroll owner、server runtime-only auth/provider
+設定規則、optional identity mirror 的 best-effort 邊界，以及 QA 的
+`scroll-owner-count` browser evidence。0.7.22 加入 provider catalogue authority check、field/variant sync report、
+supply/display lifecycle state、site-owned slug proposal、withdrawal ending、
+retirement evidence audit，以及 runtime QA assertion lint。
 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
@@ -76,6 +81,14 @@ maggie service capability-audit --project . \
   --catalogue .maggie/booking/services.json \
   --capabilities-file .maggie/booking/provider-capabilities.json \
   --fixture .maggie/booking/fixtures/provider.json
+
+# Provider catalogue and withdrawal lifecycle review
+maggie service catalogue-check "<provider-location-url>" \
+  --treatment "Lymphatic drainage massage"
+maggie service sync-report --project .
+maggie service retirement-audit --project . \
+  --catalogue .maggie/booking/services.json \
+  --evidence .maggie/booking/retirement-evidence.json
 ```
 
 完整中文說明、19 個 skills 清單和 roadmap：

package/bin/maggie.js

@@ -100,6 +100,9 @@ Usage:
   maggie design status <job-id>
   maggie service import <provider-url> --project PATH
   maggie service sync <provider-url> --project PATH
+  maggie service catalogue-check <provider-url> --treatment NAME
+  maggie service sync-report --project PATH
+  maggie service retirement-audit --project PATH --evidence FILE
   maggie service generate --project PATH
   maggie service capability-audit --project PATH --catalogue FILE --capabilities-file FILE --fixture FILE
   maggie service validate --project PATH
@@ -120,7 +123,7 @@ Usage:
   maggie localization <extract|plan|generate|preview|validate|review|publish|stale|glossary> [options]
   maggie seo performance|images|sitemap|indexnow|social-cards|head-tags [options] (sitemap supports strict validate and agent-files)
   maggie feedback <collect|preview|submit|list> [options]
-  maggie qa <start|record|summary|export> [options]
+  maggie qa <start|record|summary|export|assertion-audit> [options]
   maggie site-audit URL [--crawl] [--access-log FILE] [--require-sitemap-request] [--languages en-GB,es-MX,ja-JP] [--check-hreflang]
   maggie site-audit URL --crawl --save-baseline FILE --reviewer NAME
   maggie site-audit URL --crawl --baseline FILE

package/bundled-contracts/maggiedash/auth-model.md

@@ -19,6 +19,17 @@ and passwordless login are not supported by this contract.
 - Every project request must check membership and role after session
   validation; a valid account alone does not grant project access.
 
+## Runtime configuration boundary
+
+The host adapter reads database, session, and external identity-provider
+settings from server runtime configuration. Private settings must not come
+from browser/public environment variables, dashboard props, or client bundles.
+The primary provider session is the source of truth for the login response.
+An optional local identity/profile mirror may run afterward, but missing mirror
+tables or temporary mirror failures must not reject an otherwise valid session.
+Hosts that require the mirror must declare that requirement in their adapter
+contract and test its failure path separately.
+
 ## Local fixture adapter
 
 `tools/runtime/maggie_auth.py` provides a dependency-free SQLite fixture. It

package/bundled-references/maggiedash-integration.md

@@ -29,6 +29,10 @@ in environment variables and are never copied into reports.
 - Auth is traditional email/password with verified email, Argon2id production
   hashing, server-side sessions, project membership, and audit events. Passkey,
   WebAuthn, and passwordless login are not supported.
+- Auth and provider configuration are server-runtime-only. An optional local
+  identity/profile mirror runs after the primary session and cannot turn a
+  successful provider login into a generic failure unless the host contract
+  explicitly declares that mirror required.
 - API Pull, booking, analytics, email, and deployment providers expose health,
   normalized errors, and explicit configuration schemas.
 

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

@@ -57,7 +57,7 @@ The stable model is deliberately small and provider-neutral:
 - **category**: `level1` and `level2`; a service may belong to more than one
   provider category through `additional.provider.categories`;
 - **service**: identity, slug, title, description, active/archived status,
-  timestamps, and variants;
+  timestamps, supply/display state, and variants;
 - **variant**: identity, display name, duration, price, currency, discount or
   price range when the provider exposes them;
 - **booking actions**: booking URL, payment URL, and optional action metadata;
@@ -67,6 +67,44 @@ The stable model is deliberately small and provider-neutral:
 - **sync**: source, fetched time, content hash, parser version, and change
   status.
 
+The portable lifecycle model keeps two owners separate:
+
+- `supplyState`: provider sync state, either `live` or `withdrawn`;
+- `displayState`: human publication decision, either `published`, `hidden`, or
+  `retired`.
+
+Sync may change `supplyState` when the provider adds or removes a service, but
+must preserve `displayState`. A withdrawn/published record is an explicit
+interim state: keep the URL answerable, suppress booking and indexing, and
+open a human retirement decision. The legacy `status` field may remain for
+backwards compatibility, but it must not be used as both provider availability
+and display policy.
+
+The `slug` is site-owned. A provider rename may produce a `slugProposal` in a
+sync report, but the stored slug remains unchanged until a person accepts the
+proposal and the host writes the new slug plus its redirect in one transaction.
+
+## Withdrawal and retirement contract
+
+Provider removal is not permission to delete a public route. The adapter keeps
+the record with `supplyState: "withdrawn"` and the host chooses a reviewed
+`retirement.ending`:
+
+| Ending | Required host response | Required safety signals |
+|---|---|---|
+| `pending` | HTTP 200 interim page | unavailable notice, no booking action, `noindex`, absent from sitemap |
+| `redirect` | HTTP 301 or 308 to a different same-site route | no booking action, absent from sitemap |
+| `tombstone` | HTTP 200 unavailable page | unavailable notice, no booking action, `noindex`, absent from sitemap |
+| `gone` | HTTP 410 | no booking action, absent from sitemap |
+
+The host must preserve the old route long enough to apply its chosen ending,
+and must not return a generic 404 as a substitute for the reviewed contract.
+`maggie service retirement-audit` validates sanitized runtime evidence against
+the catalogue and records only service IDs, ending decisions, statuses, and
+safe pass/fail metadata. It does not fetch private routes, store response
+bodies, or invent redirect targets. A person must review redirect destination,
+copy, and accessibility before publication.
+
 The service page must render only canonical fields. `additional` is an
 explicit extension point for provider-specific or future fields and must be
 namespaced by concern (`provider`, `location`, `presentation`, `compliance`,
@@ -74,6 +112,21 @@ namespaced by concern (`provider`, `location`, `presentation`, `compliance`,
 nullable-safe, and must never override canonical fields. Unknown data stays in
 `additional`; it is not guessed into the stable model.
 
+## Source ownership and onboarding precedence
+
+When a host onboarding flow collects a value directly from the merchant, that
+explicit value is authoritative for the project. Provider research, imported
+profiles, search results, and inferred metadata may fill an empty field only;
+they must never replace a non-empty merchant entry. Persist the source of each
+value when the host supports it, and show a conflict for human review when two
+non-empty sources disagree. This rule applies to the website URL as well as
+business name, address, phone, category, and booking-provider identity.
+
+The shared service-booking parser does not implement a host's onboarding UI.
+Adapters must enforce this precedence before passing project identity into
+provider research or sync. A provider URL is evidence about the provider
+catalogue, not permission to overwrite the merchant's website URL.
+
 Pages can also enter the model without a provider. A normal page conversion
 creates a `draft` service with `additional.conversion.sourcePage` and no
 invented price, duration, or booking URL. It becomes `active` only after the
@@ -104,6 +157,14 @@ silent conversion, idempotent add/update/archive synchronisation, source
 snapshots/checksums, import-run audit records and generated service pages with
 provider booking CTAs.
 
+When a provider exposes an authoritative venue-owned catalogue, use that
+adapter extraction for sync decisions and treatment-presence checks. Generic
+JSON-LD, navigation links, and page-wide text can contain marketplace or other
+business entities and are not proof that the connected venue still sells a
+treatment. A read-only catalogue query should call the same parser as import
+and sync so an operator can review a reproducible answer before applying a
+withdrawal.
+
 It must not claim real-time availability, booking creation, cancellation sync
 or webhooks unless an official Fresha partner/API capability is available for
 that account. Public booking links remain the safe fallback. The paid Fresha

package/bundled-skills/maggie-auth-reference/SKILL.md

@@ -2,7 +2,7 @@
 name: maggie-auth-reference
 description: Generate and validate a provider-neutral traditional email/password auth reference with secure server sessions and production security gates.
 metadata:
-  version: 1.0.0
+  version: 1.1.0
 ---
 
 Before and after a meaningful auth-reference run, follow the shared
@@ -26,3 +26,16 @@ HttpOnly/SameSite server-side sessions, generic failed-login responses,
 throttling, lockout, revocation, and an explicit owner setup gate. Secrets,
 hashes, and session tokens must never be emitted into browser responses,
 logs, or project context.
+
+## Runtime provider boundary
+
+Read database, session, and external identity-provider settings inside the
+server route from the deployment platform's runtime configuration. Do not use
+browser/public environment variables for private settings, and do not pass
+provider credentials through dashboard props or client bundles.
+
+If a host also mirrors an authenticated identity into a local user/profile
+table, run that mirror after the primary provider session succeeds. A missing
+optional table or temporary mirror failure must be a safe, redacted warning and
+must not reject a valid primary session. Make the mirror blocking only when the
+host has explicitly documented it as part of the authentication contract.

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

@@ -303,6 +303,9 @@ shell is reconciled. Record:
   responsive changes, comparing every value with the homepage tokens;
 - hover, focus, open, loading, empty, error, scroll, tab, and reduced-motion
   behavior;
+- each modal or drawer has one intentional scroll owner. Lock the page/app
+  shell while it is open, contain the backdrop, and let only the content area
+  scroll when the dialog is taller than the viewport;
 - required assets and their reuse/licensing notes;
 - page metadata and whether the page is a marketing route, conversion route,
   or actual blog content.

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

@@ -2,7 +2,7 @@
 name: maggie-qa-workflow
 description: Run scenario-based browser QA with explicit evidence, fix/retest lifecycle, and release-gate decisions for web projects.
 metadata:
-  version: 1.0.0
+  version: 1.1.0
 ---
 
 # Maggie QA Workflow
@@ -74,6 +74,28 @@ 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.
 
+## Assert the requirement at runtime
+
+Do not use a source class, edited markup fragment, or implementation detail as
+the proof of a user-facing requirement. Describe runtime assertions in a
+project-local manifest and lint it before recording a passing scenario:
+
+```bash
+maggie qa assertion-audit --project . \
+  --assertions .maggie/qa-assertions.json \
+  --output docs/qa-assertion-audit.json
+```
+
+The `maggie.qa-assertions.v1` manifest requires a route, `transport: "http"`,
+HTTP status evidence, a screenshot/reference, and boolean results for runtime
+checks such as `text-present`, `text-absent`, `meta`, `link-absent`, or
+`redirect`. For dialogs and drawers, `scroll-owner-count` records the browser
+runtime's computed number of intentional scroll owners and must use
+`expected: 1`. Source/class/markup-only checks are rejected. The audit stores
+assertion IDs and safe pass/fail metadata, never response bodies, credentials,
+or cookies. A passing assertion audit complements browser evidence; it does
+not replace the host adapter's actual HTTP and screenshot capture.
+
 ## Gate and release evidence
 
 The run gate is `fail` when any scenario fails, `blocked` when there is no

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

@@ -2,7 +2,7 @@
 name: maggie-service-booking
 description: Import, synchronise, validate, and design SPA service pages from a booking provider such as Fresha. Use for service catalogues, treatment variants, prices, durations, booking links, payment links, and booking-aware page generation.
 metadata:
-  version: 1.1.0
+  version: 1.2.0
 ---
 
 # Maggie Service Booking
@@ -49,6 +49,13 @@ passed the provider capability check. A project without Fresha may use Google
 Calendar as a simple fallback, but it must be recorded as a separate
 BookingProvider.
 
+If onboarding also asks the merchant for a website or business identity, the
+merchant's non-empty answer owns that field. Imported provider/profile/search
+values are fallback evidence for empty fields only; a disagreement must become
+a visible review item, never a silent replacement. This skill does not own the
+host onboarding UI, so enforce the rule in the host adapter before starting
+provider research.
+
 ## CLI workflow
 
 Run from the project root:
@@ -62,6 +69,8 @@ python3 tools/clis/maggie_service_booking.py sync \
   "https://www.fresha.com/a/spa-chevy-chase-chevy-chase-4500-north-park-avenue-sbic60h4?pId=512061" \
   --project .
 
+python3 tools/clis/maggie_service_booking.py sync-report --project .
+
 python3 tools/clis/maggie_service_booking.py generate --project . --copy-data docs/service-page-copy.json
 python3 tools/clis/maggie_service_booking.py validate --project .
 
@@ -116,17 +125,40 @@ python3 tools/clis/maggie_service_booking.py capability-audit \
   --catalogue .maggie/booking/services.json \
   --capabilities-file .maggie/booking/provider-capabilities.json \
   --fixture .maggie/booking/fixtures/provider.json
+
+# Answer whether provider-owned treatments are present using the same parser
+# as import/sync; do not search the whole provider page for a name.
+python3 tools/clis/maggie_service_booking.py catalogue-check \
+  "https://www.fresha.com/a/your-location" \
+  --provider fresha --treatment "Lymphatic drainage massage"
+
+python3 tools/clis/maggie_service_booking.py retirement-audit \
+  --project . \
+  --catalogue .maggie/booking/services.json \
+  --evidence .maggie/booking/retirement-evidence.json
 ```
 
 `import` creates the first catalogue. `sync` compares the newly imported
 catalogue with the previous snapshot and records `added`, `updated`,
-`removed`, and `unchanged` services. Removed services are archived in the
-manifest before any page is deleted. `generate` is retained as a compatibility
+`removed`, and `unchanged` services. Updated records include field-level
+before/after values, variant-level changes, and any pending slug proposal.
+`sync-report` is read-only and loads a saved `maggie-service-sync-report.v1`
+artifact for review. Removed services are archived in the manifest before any
+page is deleted. `generate` is retained as a compatibility
 guard and refuses to author public copy. The AI agent and the MaggieDash renderer
 must consume an approved copy artifact instead. `run` executes parse → persist
 → validate, then stops before public generation until an AI-authored copy
 artifact and editorial review are present; it records `.maggie/booking/job.json`.
 `inspect` is read-only and `status` reports the latest job state.
+`catalogue-check` is read-only and answers one or more treatment-presence
+questions from the same provider-owned extraction used by `import` and `sync`.
+It does not use arbitrary page links or marketplace JSON-LD as evidence when
+the provider exposes an authoritative embedded catalogue.
+`retirement-audit` is also read-only. It consumes a sanitized host-browser/HTTP
+evidence artifact and validates the selected ending (`pending`, `redirect`,
+`tombstone`, or `gone`), HTTP status, booking suppression, unavailable/noindex
+signals, and sitemap exclusion. It never stores response bodies or decides a
+redirect destination for the host.
 `convert-page` imports a normal page as a draft service without inventing
 booking facts. `match-pages` reads filesystem pages plus `docs/pages.json` and
 `docs/page-content.json`, writes candidate evidence to both `.maggie/booking`
@@ -220,6 +252,19 @@ Every active service must have:
 - a booking URL, and a payment URL only when explicitly supplied;
 - provider, source URL, `firstSeenAt`, `lastSeenAt`, and sync status.
 
+The portable catalogue also carries `supplyState` (`live` or `withdrawn`) and
+`displayState` (`published`, `hidden`, or `retired`). The sync owns only
+`supplyState`; it must preserve a person's `displayState` and must not silently
+republish a hidden or retired service. Keep legacy `status` only for
+compatibility, never as both meanings at once.
+
+Withdrawn services remain available for an explicit retirement decision. Set
+`retirement.ending` to `pending` while a host still serves a safe interim
+response, or to an approved `redirect`, `tombstone`, or `gone` ending. A
+withdrawn route must suppress booking and sitemap inclusion; the host owns the
+actual route/HTTP implementation and supplies sanitized evidence to
+`retirement-audit` before release.
+
 The canonical shape is documented in
 [`references/universal-booking-adapter.md`](../../references/universal-booking-adapter.md).
 Do not invent prices, availability, practitioner claims, ratings, medical

package/bundled-tools/clis/maggie_qa_workflow.py

@@ -22,6 +22,9 @@ from urllib.parse import urlsplit, urlunsplit
 DEFAULT_SCENARIOS = Path(".maggie") / "scenario-manifest.json"
 VALID_STATUSES = {"pending", "pass", "fail", "blocked", "inconclusive"}
 VALID_PHASES = {"test", "fix", "retest"}
+ASSERTION_SCHEMA = "maggie.qa-assertions.v1"
+RUNTIME_ASSERTION_TYPES = {"http-status", "final-url", "text-present", "text-absent", "meta", "link-absent", "redirect", "scroll-owner-count"}
+SOURCE_ASSERTION_TYPES = {"class-present", "class-absent", "markup-present", "markup-absent", "source-text"}
 SECRET_RE = re.compile(
     r"(?i)(bearer\s+|(?:api[_-]?key|token|secret|password|authorization|cookie)\s*[=:]\s*)[^\s,;]+"
 )
@@ -314,6 +317,93 @@ def export_run(args: argparse.Namespace) -> int:
     return 0
 
 
+def assertion_audit(args: argparse.Namespace) -> int:
+    """Ensure QA assertions test the served requirement, not edited source markup."""
+    project = project_root(args.project)
+    manifest_path = project_root(args.assertions) if Path(args.assertions).is_absolute() else project / args.assertions
+    manifest = load_json(manifest_path)
+    errors = []
+    records = manifest.get("assertions")
+    if manifest.get("schemaVersion") != ASSERTION_SCHEMA:
+        errors.append(f"manifest schemaVersion must be {ASSERTION_SCHEMA}")
+    if not isinstance(records, list) or not records:
+        errors.append("assertions must be a non-empty array")
+        records = []
+    seen = set()
+    audited = []
+    for index, item in enumerate(records):
+        item_errors = []
+        if not isinstance(item, dict):
+            audited.append({"id": f"assertion-{index + 1}", "passed": False, "errors": ["assertion must be an object"]})
+            continue
+        identifier = safe_text(item.get("id"), 120) or f"assertion-{index + 1}"
+        if identifier in seen:
+            item_errors.append("assertion id is duplicated")
+        seen.add(identifier)
+        if not safe_text(item.get("requirement"), 1000):
+            item_errors.append("requirement is required")
+        route = safe_text(item.get("route"), 500)
+        if not route or not route.startswith("/"):
+            item_errors.append("route must be a path on the tested site")
+        if item.get("transport") != "http":
+            item_errors.append("transport must be http runtime evidence")
+        evidence_data = item.get("evidence")
+        if not isinstance(evidence_data, dict):
+            item_errors.append("evidence must be an object")
+            evidence_data = {}
+        if not safe_text(evidence_data.get("screenshot"), 500):
+            item_errors.append("evidence.screenshot is required")
+        if not isinstance(evidence_data.get("httpStatus"), int) or isinstance(evidence_data.get("httpStatus"), bool):
+            item_errors.append("evidence.httpStatus must be an integer")
+        checks = item.get("checks")
+        if not isinstance(checks, list) or not checks:
+            item_errors.append("checks must be a non-empty array")
+            checks = []
+        if not any(isinstance(check, dict) and check.get("type") == "http-status" for check in checks):
+            item_errors.append("at least one http-status check is required")
+        for check_index, check in enumerate(checks):
+            if not isinstance(check, dict):
+                item_errors.append(f"checks[{check_index}] must be an object")
+                continue
+            check_type = check.get("type")
+            surface = check.get("surface")
+            if check_type in SOURCE_ASSERTION_TYPES or surface == "source":
+                item_errors.append(f"checks[{check_index}] is source/markup-only; assert the served route instead")
+            if check_type not in RUNTIME_ASSERTION_TYPES:
+                item_errors.append(f"checks[{check_index}] has an unsupported runtime assertion type")
+            if surface not in {"http", "browser-runtime"}:
+                item_errors.append(f"checks[{check_index}] must identify http or browser-runtime evidence")
+            if not isinstance(check.get("passed"), bool):
+                item_errors.append(f"checks[{check_index}].passed must be boolean evidence")
+            if check_type == "http-status" and isinstance(evidence_data.get("httpStatus"), int) and check.get("actual") != evidence_data["httpStatus"]:
+                item_errors.append(f"checks[{check_index}] actual status does not match evidence.httpStatus")
+            if check_type == "scroll-owner-count":
+                if not isinstance(check.get("actual"), int) or isinstance(check.get("actual"), bool):
+                    item_errors.append(f"checks[{check_index}].actual must be an integer scroll-owner count")
+                if check.get("expected") != 1:
+                    item_errors.append(f"checks[{check_index}].expected must be 1 scroll owner")
+                if isinstance(check.get("actual"), int) and not isinstance(check.get("actual"), bool) and check.get("actual") != 1:
+                    item_errors.append(f"checks[{check_index}] found more or fewer than one scroll owner")
+        if any(isinstance(check, dict) and check.get("passed") is False for check in checks):
+            item_errors.append("one or more runtime checks failed")
+        audited.append({"id": identifier, "passed": not item_errors, "errors": item_errors})
+    passed = not errors and all(item.get("passed") for item in audited) and bool(audited)
+    report = {
+        "schemaVersion": "maggie.qa-assertion-audit.v1",
+        "assertionSchema": ASSERTION_SCHEMA,
+        "checked": len(audited),
+        "assertions": audited,
+        "errors": errors,
+        "passed": passed,
+    }
+    output = Path(args.output).expanduser()
+    if not output.is_absolute():
+        output = project / output
+    write_json(output, report)
+    print(json.dumps({"status": "passed" if passed else "failed", "report": str(output.resolve()), "checked": len(audited), "errors": errors}, ensure_ascii=False, indent=2))
+    return 0 if passed else 1
+
+
 def parser() -> argparse.ArgumentParser:
     root = argparse.ArgumentParser(description=__doc__)
     root.add_argument("--project", default=".")
@@ -350,6 +440,10 @@ def parser() -> argparse.ArgumentParser:
         command.add_argument("--run", required=True)
         if name == "summary": command.add_argument("--format", choices=("json", "markdown"), default="json")
         else: command.add_argument("--output", required=True)
+    assertion_parser = commands.add_parser("assertion-audit")
+    assertion_parser.add_argument("--project", default=argparse.SUPPRESS)
+    assertion_parser.add_argument("--assertions", required=True, help="runtime assertion manifest JSON")
+    assertion_parser.add_argument("--output", default=".maggie/qa-assertion-audit.json")
     return root
 
 
@@ -359,6 +453,7 @@ def main() -> int:
         if args.command == "start": return start(args)
         if args.command == "record": return record(args)
         if args.command == "summary": return summary(args)
+        if args.command == "assertion-audit": return assertion_audit(args)
         return export_run(args)
     except (OSError, ValueError, json.JSONDecodeError) as error:
         print(f"QA workflow error: {safe_text(error)}", file=sys.stderr)

package/bundled-tools/clis/maggie_service_booking.py

@@ -17,6 +17,8 @@ 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)
 DURATION = re.compile(r"(\d{2,3})\s*(?:min|mins|minutes?)", re.I)
+SUPPLY_STATES = {"live", "withdrawn"}
+DISPLAY_STATES = {"published", "hidden", "retired"}
 
 def slug(value):
     value = re.sub(r"[^a-z0-9]+", "-", value.lower()).strip("-")
@@ -57,33 +59,37 @@ def flatten(value):
 
 def parse(source, provider):
     raw=fetch(source); parser=Extractor(); parser.feed(raw); records=[]
+    embedded_marker = provider == "fresha" and re.search(r'"services"\s*:\s*\[', raw)
     if provider == "fresha":
         records.extend(parse_fresha_embedded(raw, source))
-    for obj in json_objects(parser.scripts):
-        for item in flatten(obj):
-            typ=item.get("@type", "")
-            types=set(typ) if isinstance(typ, list) else {typ}
-            if not types.intersection({"Service","Product","Offer","ListItem"}) and not any(k in item for k in ("duration","price","providerServiceId")): continue
-            name=item.get("name") or item.get("title") or (item.get("item") or {}).get("name") if isinstance(item.get("item"),dict) else item.get("name")
-            if not name or len(str(name)) < 3: continue
-            offers=item.get("offers") if isinstance(item.get("offers"),list) else [item.get("offers", item)]
-            variants=[]
-            for offer in offers:
-                if not isinstance(offer,dict): offer={}
-                text=" ".join(str(offer.get(k,"")) for k in ("name","description","duration"))
-                dm=DURATION.search(text); price=offer.get("price")
-                if price is None:
-                    match=MONEY.search(text); price=match.group(1).replace(",","") if match else None
-                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
-                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))
-            records.append(make_record(provider, source, pid, str(name), str(item.get("description") or ""), variants, url, parser.links))
-    if not records:
+    # A provider-specific authoritative catalogue is the only service source.
+    # Generic JSON-LD may include marketplace entities for another business.
+    if not embedded_marker:
+        for obj in json_objects(parser.scripts):
+            for item in flatten(obj):
+                typ=item.get("@type", "")
+                types=set(typ) if isinstance(typ, list) else {typ}
+                if not types.intersection({"Service","Product","Offer","ListItem"}) and not any(k in item for k in ("providerServiceId","productID","sku")): continue
+                name=item.get("name") or item.get("title") or (item.get("item") or {}).get("name") if isinstance(item.get("item"),dict) else item.get("name")
+                if not name or len(str(name)) < 3: continue
+                offers=item.get("offers") if isinstance(item.get("offers"),list) else [item.get("offers", item)]
+                variants=[]
+                for offer in offers:
+                    if not isinstance(offer,dict): offer={}
+                    text=" ".join(str(offer.get(k,"")) for k in ("name","description","duration"))
+                    dm=DURATION.search(text); price=offer.get("price")
+                    if price is None:
+                        match=MONEY.search(text); price=match.group(1).replace(",","") if match else None
+                    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
+                    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))
+                records.append(make_record(provider, source, pid, str(name), str(item.get("description") or ""), variants, url, parser.links))
+    if not records and not embedded_marker:
         for _, pieces in parser.headings:
             name=" ".join(pieces).strip()
             if len(name)>3: records.append(make_record(provider, source, slug(name), name, "", [], None, parser.links))
@@ -97,10 +103,10 @@ def parse(source, provider):
 def parse_fresha_embedded(raw, source):
     """Read the public service catalogue embedded in Fresha's Next data."""
     records=[]
-    marker='"services":['; start=raw.find(marker)
-    if start >= 0:
+    marker=re.search(r'"services"\s*:\s*\[', raw); start=marker.start() if marker else -1
+    if marker:
         try:
-            groups=json.JSONDecoder().raw_decode(raw[start+len('"services":'):])[0]
+            groups=json.JSONDecoder().raw_decode(raw[marker.end()-1:])[0]
         except (ValueError, TypeError): groups=[]
         for group in groups if isinstance(groups,list) else []:
             level1=str(group.get("name") or "Uncategorised").strip()
@@ -182,7 +188,7 @@ def make_record(provider, source, pid, name, description, variants, booking, lin
     if not booking:
         for href,_ in links:
             if any(x in href.lower() for x in ("book","appointment","checkout")): booking=urljoin(source,href); break
-    return {"id":f"{provider}:{pid}","provider":provider,"providerServiceId":pid,"slug":slug(name),"title":name,"description":description.strip(),"sourceUrl":source,"category":{"level1":"Uncategorised","level2":None},"variants":variants,"bookingUrl":booking,"paymentUrl":None,"status":"active","firstSeenAt":NOW(),"lastSeenAt":NOW()}
+    return {"id":f"{provider}:{pid}","provider":provider,"providerServiceId":pid,"slug":slug(name),"title":name,"description":description.strip(),"sourceUrl":source,"category":{"level1":"Uncategorised","level2":None},"variants":variants,"bookingUrl":booking,"paymentUrl":None,"status":"active","supplyState":"live","displayState":"published","firstSeenAt":NOW(),"lastSeenAt":NOW()}
 
 def root(args): return Path(args.project).resolve()
 def path(project): return project/".maggie"/"booking"/"services.json"
@@ -199,11 +205,15 @@ def validate(data):
             if not s.get(key): errors.append(f"{s.get('id','unknown')}: missing {key}")
         if s.get("id") in seen: errors.append(f"duplicate service id: {s['id']}")
         seen.add(s.get("id"));
+        supply=s.get("supplyState") or ("withdrawn" if s.get("status") in {"archived", "removed"} else "live")
+        display=s.get("displayState") or ("retired" if s.get("status") == "archived" else "published")
+        if supply not in SUPPLY_STATES: errors.append(f"{s.get('id')}: invalid supplyState")
+        if display not in DISPLAY_STATES: errors.append(f"{s.get('id')}: invalid displayState")
         if any(x.get("slug")==s.get("slug") for x in data.get("services",[]) if x is not s): errors.append(f"duplicate service slug: {s.get('slug')}")
         pages=s.get("pages",[])
         if not isinstance(pages,list): errors.append(f"{s.get('id')}: pages must be an array"); pages=[]
         if sum(p.get("role")=="canonical" for p in pages if isinstance(p,dict))>1: errors.append(f"{s.get('id')}: multiple canonical pages")
-        if s.get("status")=="active" and not s.get("variants"): errors.append(f"{s.get('id')}: no variants")
+        if supply == "live" and not s.get("variants"): errors.append(f"{s.get('id')}: no variants")
         for v in s.get("variants",[]):
             if not v.get("durationMinutes") or not v.get("price",{}).get("currency"): errors.append(f"{s.get('id')}: incomplete variant {v.get('id')}")
         for key in ("bookingUrl","paymentUrl"):
@@ -312,33 +322,172 @@ def cmd_fact_audit(args):
     print(json.dumps({"status": "passed" if report["passed"] else "failed", "report": str(out), "reviewQueue": str(queue_path), "services": len(services), "variants": len(seen_variants), "sourceUrlsBackfilled": changed, "errors": errors[:20], "errorCount": len(errors), "publish": False}, indent=2, ensure_ascii=False))
     return 0 if report["passed"] else 1
 
+def cmd_catalogue_check(args):
+    """Answer treatment-presence questions using the import/sync parser."""
+    try:
+        data = parse(args.source, args.provider)
+    except (OSError, ValueError, UnicodeError):
+        print(json.dumps({"status": "failed", "error": "source could not be parsed"}, indent=2))
+        return 1
+    services = data.get("services", [])
+    results = []
+    for query in args.treatment:
+        query_tokens = page_tokens(query)
+        matches = [
+            {"id": service.get("id"), "title": service.get("title"), "category": service.get("category", {}).get("level1")}
+            for service in services
+            if query_tokens and query_tokens <= page_tokens(service.get("title", ""))
+        ]
+        results.append({"treatment": query, "status": "found" if matches else "not-found", "matches": matches})
+    passed = all(item["status"] == "found" for item in results)
+    print(json.dumps({"status": "passed" if passed else "failed", "provider": args.provider, "serviceCount": len(services), "results": results}, indent=2, ensure_ascii=False))
+    return 0 if passed else 1
+
+RETIREMENT_SCHEMA = "maggie-service-retirement-evidence.v1"
+RETIREMENT_ENDINGS = {"pending", "redirect", "tombstone", "gone"}
+
+def cmd_retirement_audit(args):
+    """Validate sanitized runtime evidence for withdrawn service URLs."""
+    project=root(args); catalogue_path=Path(args.catalogue); catalogue_path=catalogue_path if catalogue_path.is_absolute() else project/catalogue_path
+    evidence_path=Path(args.evidence); evidence_path=evidence_path if evidence_path.is_absolute() else project/evidence_path
+    try:
+        catalogue=json.loads(catalogue_path.read_text(encoding="utf-8")); evidence=json.loads(evidence_path.read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        print(json.dumps({"status":"failed","error":"catalogue or retirement evidence is invalid"},indent=2)); return 1
+    services={str(item.get("id")):item for item in catalogue.get("services",[]) if isinstance(item,dict) and item.get("id")}
+    rows=evidence.get("services") if isinstance(evidence,dict) else None
+    errors=[]; results=[]
+    if not isinstance(evidence,dict) or evidence.get("schemaVersion") != RETIREMENT_SCHEMA:
+        errors.append(f"evidence schemaVersion must be {RETIREMENT_SCHEMA}")
+    if not isinstance(rows,list):
+        errors.append("evidence.services must be a non-empty array")
+        rows=[]
+    if isinstance(rows,list) and not rows: errors.append("evidence.services must be a non-empty array")
+    seen=set()
+    for index,row in enumerate(rows):
+        item_errors=[]
+        if not isinstance(row,dict):
+            results.append({"index":index,"passed":False,"errors":["evidence row must be an object"]}); continue
+        service_id=str(row.get("serviceId") or "")
+        if not service_id or service_id in seen: item_errors.append("serviceId is missing or duplicated")
+        seen.add(service_id)
+        service=services.get(service_id)
+        if not service: item_errors.append("service is not in the catalogue")
+        supply=(service or {}).get("supplyState") or ("withdrawn" if (service or {}).get("status") in {"archived","removed"} else "live")
+        if supply != "withdrawn": item_errors.append("retirement evidence requires a withdrawn service")
+        ending=str(row.get("ending") or "")
+        if ending not in RETIREMENT_ENDINGS: item_errors.append("ending must be pending, redirect, tombstone, or gone")
+        expected_ending=((service or {}).get("retirement") or {}).get("ending")
+        if expected_ending and expected_ending != ending: item_errors.append("evidence ending does not match the catalogue decision")
+        status=row.get("httpStatus")
+        if not isinstance(status,int) or isinstance(status,bool): item_errors.append("httpStatus must be an integer")
+        if row.get("inSitemap") is not False: item_errors.append("withdrawn service must be absent from the sitemap")
+        if row.get("bookingSuppressed") is not True: item_errors.append("bookingSuppressed must be true")
+        if ending in {"pending","tombstone"}:
+            if status != 200: item_errors.append(f"{ending} must return HTTP 200")
+            if row.get("unavailableNotice") is not True: item_errors.append("unavailableNotice must be true")
+            if row.get("noindex") is not True: item_errors.append("noindex must be true")
+        elif ending == "redirect":
+            if status not in {301,308}: item_errors.append("redirect must return HTTP 301 or 308")
+            location=str(row.get("location") or "")
+            route=str(row.get("route") or "")
+            if not location or not location.startswith("/") or location == route: item_errors.append("redirect needs a different same-site location")
+        elif ending == "gone" and status != 410:
+            item_errors.append("gone must return HTTP 410")
+        results.append({"serviceId":service_id,"ending":ending,"passed":not item_errors,"errors":item_errors})
+    passed=not errors and bool(results) and all(item["passed"] for item in results)
+    report={"schemaVersion":"maggie-service-retirement-audit.v1","evidenceSchema":RETIREMENT_SCHEMA,"checked":len(results),"services":results,"errors":errors,"passed":passed}
+    output=Path(args.output).expanduser(); output=output if output.is_absolute() else project/output; output.parent.mkdir(parents=True,exist_ok=True); output.write_text(json.dumps(report,indent=2,ensure_ascii=False)+"\n",encoding="utf-8")
+    print(json.dumps({"status":"passed" if passed else "failed","report":str(output.resolve()),"checked":len(results),"errors":errors},indent=2)); return 0 if passed else 1
+
 def cmd_import(args):
     project=root(args); data=parse(args.source,args.provider); old=load(project) if path(project).exists() else {"services":[]}; previous={s["id"]:s for s in old.get("services",[])}
     for service in data.get("services",[]):
         if service["id"] in previous:
-            service["pages"]=previous[service["id"]].get("pages",[]); service["additional"]={**previous[service["id"]].get("additional",{}),**service.get("additional",{})}
+            old_service=previous[service["id"]]
+            preserve_site_fields(service, old_service)
+            service["displayState"]=old_service.get("displayState") or ("retired" if old_service.get("status") == "archived" else "published")
+        service.setdefault("supplyState", "live"); service.setdefault("displayState", "published")
     errors=validate(data)
     if errors: print(json.dumps({"status":"failed","errors":errors},indent=2)); return 1
     save(project,data); print(json.dumps({"status":"imported","path":str(path(project)),"reviewPath":str(project/"docs"/"services.json"),"services":len(data["services"])},indent=2)); return 0
+
+SERVICE_DIFF_FIELDS = ("provider", "providerServiceId", "slug", "title", "description", "category", "bookingUrl", "paymentUrl", "status", "supplyState", "displayState", "retirement")
+
+def preserve_site_fields(service, old_service):
+    proposal=None
+    old_slug=str(old_service.get("slug") or "")
+    new_slug=str(service.get("slug") or "")
+    if old_slug and new_slug and old_slug != new_slug:
+        proposal={"status":"pending","from":old_slug,"to":new_slug,"reason":"provider name implies a different public slug"}
+        service["slug"]=old_slug
+    service["pages"] = old_service.get("pages", [])
+    service["additional"] = {**old_service.get("additional", {}), **service.get("additional", {})}
+    return proposal
+
+def service_diff(before, after):
+    fields=[]
+    for field in SERVICE_DIFF_FIELDS:
+        old_value = before.get(field) if isinstance(before, dict) else None
+        new_value = after.get(field) if isinstance(after, dict) else None
+        if old_value != new_value:
+            fields.append({"field": field, "before": old_value, "after": new_value})
+    old_variants={str(item.get("id")): item for item in (before or {}).get("variants", []) if isinstance(item, dict) and item.get("id")}
+    new_variants={str(item.get("id")): item for item in (after or {}).get("variants", []) if isinstance(item, dict) and item.get("id")}
+    variants=[]
+    for variant_id in sorted(set(old_variants) | set(new_variants)):
+        old_variant=old_variants.get(variant_id); new_variant=new_variants.get(variant_id)
+        if old_variant is None:
+            variants.append({"id": variant_id, "change": "added", "before": None, "after": new_variant})
+        elif new_variant is None:
+            variants.append({"id": variant_id, "change": "removed", "before": old_variant, "after": None})
+        elif old_variant != new_variant:
+            variants.append({"id": variant_id, "change": "updated", "before": old_variant, "after": new_variant})
+    return {"fields": fields, "variantChanges": variants}
+
 def cmd_sync(args):
     project=root(args); old=load(project) if path(project).exists() else {"services":[]}; fresh=parse(args.source,args.provider); previous={s["id"]:s for s in old.get("services",[])}; current={s["id"]:s for s in fresh.get("services",[])}; changes=[]
-    def comparable(service):
-        value=dict(service)
-        value.pop("firstSeenAt", None)
-        value.pop("lastSeenAt", None)
-        return value
     for sid, service in current.items():
         old_service = previous.get(sid)
+        slug_proposal=None
         if old_service:
-            service["pages"] = old_service.get("pages", [])
-            service["additional"] = {**old_service.get("additional", {}), **service.get("additional", {})}
-        changes.append({"id":sid,"change":"added" if sid not in previous else ("updated" if json.dumps(comparable(service),sort_keys=True,ensure_ascii=False)!=json.dumps(comparable(old_service),sort_keys=True,ensure_ascii=False) else "unchanged")})
+            slug_proposal=preserve_site_fields(service, old_service)
+            # Provider sync owns supply; a person's display decision survives
+            # the run and is never reset by a newly fetched row.
+            service["displayState"] = old_service.get("displayState") or ("retired" if old_service.get("status") == "archived" else "published")
+        service["supplyState"] = "live"
+        diff=service_diff(old_service, service)
+        change="added" if sid not in previous else ("updated" if diff["fields"] or diff["variantChanges"] else "unchanged")
+        if slug_proposal:
+            diff["slugProposal"]=slug_proposal
+            diff["reviewRequired"]=True
+            change="updated"
+        changes.append({"id":sid,"change":change,**diff})
     for sid, service in previous.items():
-        if sid not in current: archived={**service,"status":"archived","removedAt":NOW()}; current[sid]=archived; changes.append({"id":sid,"change":"removed"})
+        if sid not in current:
+            archived={**service,"status":"archived","supplyState":"withdrawn","displayState":service.get("displayState") or ("retired" if service.get("status") == "archived" else "published"),"retirement":service.get("retirement") or {"ending":"pending"},"removedAt":NOW()}; current[sid]=archived
+            changes.append({"id":sid,"change":"removed","fields":[{"field":"status","before":service.get("status"),"after":"archived"}],"variantChanges":[]})
     fresh["services"]=list(current.values()); save(project,fresh)
-    run_id=datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%SZ")
-    report={"schemaVersion":"1.0","runId":run_id,"syncedAt":fresh["syncedAt"],"sourceUrl":args.source,"provider":args.provider,"changes":changes,"summary":{"total":len(changes),"added":sum(c["change"]=="added" for c in changes),"updated":sum(c["change"]=="updated" for c in changes),"removed":sum(c["change"]=="removed" for c in changes),"unchanged":sum(c["change"]=="unchanged" for c in changes)},"checkpoint":{"phase":"reconciled","processed":len(changes),"total":len(changes),"resumable":True,"status":"complete"}}
+    run_id=datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%S%fZ")
+    report={"schemaVersion":"maggie-service-sync-report.v1","runId":run_id,"syncedAt":fresh["syncedAt"],"sourceUrl":args.source,"provider":args.provider,"changes":changes,"summary":{"total":len(changes),"added":sum(c["change"]=="added" for c in changes),"updated":sum(c["change"]=="updated" for c in changes),"removed":sum(c["change"]=="removed" for c in changes),"unchanged":sum(c["change"]=="unchanged" for c in changes)},"checkpoint":{"phase":"reconciled","processed":len(changes),"total":len(changes),"resumable":True,"status":"complete"}}
     sync_dir=path(project).parent/"sync-runs"; sync_dir.mkdir(parents=True,exist_ok=True); (sync_dir/f"{run_id}.json").write_text(json.dumps(report,indent=2,ensure_ascii=False)+"\n",encoding="utf-8"); (path(project).parent/"sync-checkpoint.json").write_text(json.dumps(report["checkpoint"]|{"runId":run_id,"sourceUrl":args.source},indent=2,ensure_ascii=False)+"\n",encoding="utf-8"); (path(project).parent/"last-sync.json").write_text(json.dumps(report,indent=2,ensure_ascii=False)+"\n",encoding="utf-8"); print(json.dumps(report,indent=2,ensure_ascii=False)); return 0 if not validate(fresh) else 1
+
+def cmd_sync_report(args):
+    project=root(args); directory=path(project).parent/"sync-runs"
+    candidates=sorted(directory.glob("*.json")) if directory.exists() else []
+    if args.run_id:
+        candidates=[directory/f"{args.run_id}.json"]
+    if not candidates or not candidates[-1].exists():
+        print(json.dumps({"status":"failed","error":"sync report not found"},indent=2)); return 1
+    try:
+        report=json.loads(candidates[-1].read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        print(json.dumps({"status":"failed","error":"sync report is invalid"},indent=2)); return 1
+    if report.get("schemaVersion") != "maggie-service-sync-report.v1":
+        print(json.dumps({"status":"failed","error":"unsupported sync report schema"},indent=2)); return 1
+    if args.output:
+        output=Path(args.output).expanduser(); output=output if output.is_absolute() else project/output; output.parent.mkdir(parents=True,exist_ok=True); output.write_text(json.dumps(report,indent=2,ensure_ascii=False)+"\n",encoding="utf-8")
+    print(json.dumps(report,indent=2,ensure_ascii=False)); return 0
 def cmd_generate(args):
     print(json.dumps({"status":"blocked","error":"Public copy generation is agent-owned","required":"The AI agent must create and review the copy artifact, then the project renderer must consume it. This deterministic CLI never synthesizes public hero, section, CTA, title, or FAQ copy.","copyData":getattr(args, "copy_data", None)},indent=2)); return 1
     project=root(args); data=load(project); errors=validate(data)
@@ -1004,6 +1153,7 @@ def main():
     for name in ("import","sync","run"):
         q=sub.add_parser(name); q.add_argument("source"); q.add_argument("--project",default="."); q.add_argument("--provider",default="fresha",choices=["fresha"])
         if name == "run": q.add_argument("--copy-data", help="AI-authored service copy artifact; required before public page generation")
+    q=sub.add_parser("sync-report"); q.add_argument("--project",default="."); q.add_argument("--run-id"); q.add_argument("--output")
     q=sub.add_parser("convert-page"); q.add_argument("page"); q.add_argument("--project",default=".")
     for name in ("polish","validate-polish"):
         q=sub.add_parser(name); q.add_argument("--service-id",required=True); q.add_argument("--page",required=True); q.add_argument("--project",default="."); q.add_argument("--rendered",help="rendered HTML file or URL for runtime evidence"); q.add_argument("--copy-data",required=True,help="AI-authored copy JSON with provenance and completed review statuses")
@@ -1013,6 +1163,8 @@ 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("catalogue-check"); q.add_argument("source"); q.add_argument("--project",default="."); q.add_argument("--provider",default="fresha",choices=["fresha"]); q.add_argument("--treatment",action="append",required=True,help="provider treatment name; repeat for multiple checks")
+    q=sub.add_parser("retirement-audit"); q.add_argument("--project",default="."); q.add_argument("--catalogue",default=".maggie/booking/services.json"); q.add_argument("--evidence",required=True,help="sanitized runtime retirement evidence JSON"); q.add_argument("--output",default="docs/service-retirement-audit.json")
     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")
@@ -1026,6 +1178,7 @@ def main():
     a=p.parse_args(); project=root(a)
     if a.command=="import": return cmd_import(a)
     if a.command=="sync": return cmd_sync(a)
+    if a.command=="sync-report": return cmd_sync_report(a)
     if a.command=="run": return cmd_run(a)
     if a.command=="convert-page": return cmd_convert_page(a)
     if a.command in {"polish","validate-polish"}: return cmd_polish(a)
@@ -1035,6 +1188,8 @@ 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=="catalogue-check": return cmd_catalogue_check(a)
+    if a.command=="retirement-audit": return cmd_retirement_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)

package/package.json

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

package/references/maggiedash-integration.md

@@ -29,6 +29,10 @@ in environment variables and are never copied into reports.
 - Auth is traditional email/password with verified email, Argon2id production
   hashing, server-side sessions, project membership, and audit events. Passkey,
   WebAuthn, and passwordless login are not supported.
+- Auth and provider configuration are server-runtime-only. An optional local
+  identity/profile mirror runs after the primary session and cannot turn a
+  successful provider login into a generic failure unless the host contract
+  explicitly declares that mirror required.
 - API Pull, booking, analytics, email, and deployment providers expose health,
   normalized errors, and explicit configuration schemas.
 

package/references/universal-booking-adapter.md

@@ -57,7 +57,7 @@ The stable model is deliberately small and provider-neutral:
 - **category**: `level1` and `level2`; a service may belong to more than one
   provider category through `additional.provider.categories`;
 - **service**: identity, slug, title, description, active/archived status,
-  timestamps, and variants;
+  timestamps, supply/display state, and variants;
 - **variant**: identity, display name, duration, price, currency, discount or
   price range when the provider exposes them;
 - **booking actions**: booking URL, payment URL, and optional action metadata;
@@ -67,6 +67,44 @@ The stable model is deliberately small and provider-neutral:
 - **sync**: source, fetched time, content hash, parser version, and change
   status.
 
+The portable lifecycle model keeps two owners separate:
+
+- `supplyState`: provider sync state, either `live` or `withdrawn`;
+- `displayState`: human publication decision, either `published`, `hidden`, or
+  `retired`.
+
+Sync may change `supplyState` when the provider adds or removes a service, but
+must preserve `displayState`. A withdrawn/published record is an explicit
+interim state: keep the URL answerable, suppress booking and indexing, and
+open a human retirement decision. The legacy `status` field may remain for
+backwards compatibility, but it must not be used as both provider availability
+and display policy.
+
+The `slug` is site-owned. A provider rename may produce a `slugProposal` in a
+sync report, but the stored slug remains unchanged until a person accepts the
+proposal and the host writes the new slug plus its redirect in one transaction.
+
+## Withdrawal and retirement contract
+
+Provider removal is not permission to delete a public route. The adapter keeps
+the record with `supplyState: "withdrawn"` and the host chooses a reviewed
+`retirement.ending`:
+
+| Ending | Required host response | Required safety signals |
+|---|---|---|
+| `pending` | HTTP 200 interim page | unavailable notice, no booking action, `noindex`, absent from sitemap |
+| `redirect` | HTTP 301 or 308 to a different same-site route | no booking action, absent from sitemap |
+| `tombstone` | HTTP 200 unavailable page | unavailable notice, no booking action, `noindex`, absent from sitemap |
+| `gone` | HTTP 410 | no booking action, absent from sitemap |
+
+The host must preserve the old route long enough to apply its chosen ending,
+and must not return a generic 404 as a substitute for the reviewed contract.
+`maggie service retirement-audit` validates sanitized runtime evidence against
+the catalogue and records only service IDs, ending decisions, statuses, and
+safe pass/fail metadata. It does not fetch private routes, store response
+bodies, or invent redirect targets. A person must review redirect destination,
+copy, and accessibility before publication.
+
 The service page must render only canonical fields. `additional` is an
 explicit extension point for provider-specific or future fields and must be
 namespaced by concern (`provider`, `location`, `presentation`, `compliance`,
@@ -74,6 +112,21 @@ namespaced by concern (`provider`, `location`, `presentation`, `compliance`,
 nullable-safe, and must never override canonical fields. Unknown data stays in
 `additional`; it is not guessed into the stable model.
 
+## Source ownership and onboarding precedence
+
+When a host onboarding flow collects a value directly from the merchant, that
+explicit value is authoritative for the project. Provider research, imported
+profiles, search results, and inferred metadata may fill an empty field only;
+they must never replace a non-empty merchant entry. Persist the source of each
+value when the host supports it, and show a conflict for human review when two
+non-empty sources disagree. This rule applies to the website URL as well as
+business name, address, phone, category, and booking-provider identity.
+
+The shared service-booking parser does not implement a host's onboarding UI.
+Adapters must enforce this precedence before passing project identity into
+provider research or sync. A provider URL is evidence about the provider
+catalogue, not permission to overwrite the merchant's website URL.
+
 Pages can also enter the model without a provider. A normal page conversion
 creates a `draft` service with `additional.conversion.sourcePage` and no
 invented price, duration, or booking URL. It becomes `active` only after the
@@ -104,6 +157,14 @@ silent conversion, idempotent add/update/archive synchronisation, source
 snapshots/checksums, import-run audit records and generated service pages with
 provider booking CTAs.
 
+When a provider exposes an authoritative venue-owned catalogue, use that
+adapter extraction for sync decisions and treatment-presence checks. Generic
+JSON-LD, navigation links, and page-wide text can contain marketplace or other
+business entities and are not proof that the connected venue still sells a
+treatment. A read-only catalogue query should call the same parser as import
+and sync so an operator can review a reproducible answer before applying a
+withdrawal.
+
 It must not claim real-time availability, booking creation, cancellation sync
 or webhooks unless an official Fresha partner/API capability is available for
 that account. Public booking links remain the safe fallback. The paid Fresha