@topy-ai/maggie 0.7.14 → 0.7.15

package/README.md

@@ -76,6 +76,14 @@ 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.
 
+The current package also includes reusable safeguards from the latest feedback
+review: `maggie dash api-contract` checks declared request and 2xx response
+shapes; `maggie blog check-gate`/`approve` enforces review before publish;
+sitemap validation flags suspiciously uniform `lastmod` dates; `maggie seo
+indexnow` plans only changed same-origin URLs and holds back URLs accepted in
+the last 24 hours; and dash inventory separates renderer kind from public page
+kind while reporting source coverage for code-rendered routes.
+
 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:
@@ -121,7 +129,8 @@ maggie dash install | init | status | migrate | cms ...
 maggie dash transition ...      # explicit content approval transition
 maggie dash variant ...         # service variant create/review/preview/publish
 maggie dash sections ...        # field fan-out, locale, binding, media, copy, identity keys
-maggie dash inventory ...        # disjoint published-page inventory
+maggie dash inventory ...        # disjoint renderer/page-kind inventory + coverage
+maggie dash api-contract ...     # declared API body and 2xx response contract
 maggie agent-content write ...  # host-authorized, origin-bound content bridge
 maggie verification coverage ... # changed surface/locale evidence gate
 maggie clone ...                 # authorized homepage capture
@@ -136,6 +145,7 @@ maggie service ...               # import, sync, generate, 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
+maggie seo indexnow ...           # changed URLs, key check, retry-safe 24h guard
 maggie deployment | migration | release | analytics | schedule
 maggie migration identity --identity-file FILE [--expected-file FILE]
 maggie deployment canary --asset URL=SHA256 --render-report report.json
@@ -237,8 +247,8 @@ artifact schemas.
 Recommended upgrade sequence for the current release:
 
 ```bash
-npx @topy-ai/maggie@0.7.14 update --project . --force
-npx @topy-ai/maggie@0.7.14 cleanup --project .
+npx @topy-ai/maggie@0.7.15 update --project . --force
+npx @topy-ai/maggie@0.7.15 cleanup --project .
 ```
 
 Maintainers should pass npm credentials through the repository helper, never
@@ -248,7 +258,9 @@ as a command-line argument:
 node scripts/publish-npm.mjs --maggie-env-file ../.env
 ```
 
-The 0.7.14 workflow adds the general `maggie-qa-workflow` skill and `maggie qa`
+The 0.7.15 workflow adds API contracts, blog review gates, sitemap freshness,
+change-driven IndexNow, and page-kind/source-coverage inventory. It also keeps
+the general `maggie-qa-workflow` skill and `maggie qa`
 CLI for scenario manifests, secret-free browser evidence metadata, test/fix/
 retest lifecycle, adjacent regression checks, and explicit release gates. The
 0.7.13 workflow adds field-aware section fan-out and locale coverage,
@@ -565,6 +577,8 @@ maggie design author --project . --route /about --purpose "Explain our approach"
 maggie blog init --project . --confirm
 maggie blog ingest --project . --source local --input content/posts.json --confirm
 maggie blog validate --project .
+maggie blog check-gate --project .
+maggie blog approve --project . --slug example-post --actor reviewer --reason "reviewed" --confirm
 maggie blog sitemap --project .
 ```
 

package/README.zh-TW.md

@@ -8,7 +8,7 @@ Codex、Claude Code 與相容的 coding agents。
 ## 安裝
 
 ```bash
-npx @topy-ai/maggie@0.7.14 init --agent all
+npx @topy-ai/maggie@0.7.15 init --agent all
 npx @topy-ai/maggie doctor --project .
 ```
 
@@ -25,6 +25,9 @@ maggie doctor --project . --require-bootstrap --strict
 deployment、memory、feedback 和 MaggieDash。內容先 draft/review，外部寫入、
 publish 與 production deployment 需要明確確認。
 
+0.7.15 也加入 API schema contract、blog review gate、sitemap freshness
+warning、change-driven IndexNow 與 page-kind/source-coverage inventory。
+
 MaggieDash 也提供穩定 section identity、可重用 section arrangement、機器可讀
 section registry、短期 agent content bridge，以及 translation out-of-band write
 後的 restart gate。`maggie doctor` 會比較 install manifest 與磁碟上的實際 skills。

package/bin/maggie.js

@@ -59,7 +59,8 @@ Usage:
   maggie bootstrap interview [project]
   maggie dash init|install|status|migrate|transition|variant|cms --project PATH [options]
   maggie dash sections <validate|prompt|keys|remap-translations|fanout-validate|locale-validate|variant-copy-validate|media-validate|bindings-validate|idempotency-validate|reconcile> [options]
-  maggie dash inventory --pages-file FILE
+  maggie dash inventory --pages-file FILE [--require-page-kinds] [--require-source-coverage]
+  maggie dash api-contract --spec FILE
   maggie dash components-audit --bindings-file FILE --sections-file FILE --pages-file FILE
   maggie dash status --project PATH
   maggie dash migrate --project PATH --confirm
@@ -92,7 +93,7 @@ Usage:
   maggie design step <job-id> --step NAME --evidence FILE
   maggie auth reference --project PATH --confirm
   maggie auth check --project PATH [--production]
-  maggie blog init|inspect|ingest|validate|publish|sitemap|settings|rollback|integration-state
+  maggie blog init|inspect|ingest|validate|check-gate|approve|publish|sitemap|settings|rollback|integration-state
   maggie design status <job-id>
   maggie service import <provider-url> --project PATH
   maggie service sync <provider-url> --project PATH
@@ -112,7 +113,7 @@ Usage:
   maggie api lifecycle --project PATH [--execute --allow-quota]
   maggie memory <init|list|search|context|add|record-error|transition|export> --project PATH
   maggie localization <extract|plan|generate|preview|validate|review|publish|stale|glossary> [options]
-  maggie seo performance|images|sitemap [options] (sitemap supports strict validate and agent-files)
+  maggie seo performance|images|sitemap|indexnow [options] (sitemap supports strict validate and agent-files)
   maggie feedback <collect|preview|submit|list> [options]
   maggie qa <start|record|summary|export> [options]
   maggie site-audit URL [--crawl] [--access-log FILE] [--require-sitemap-request] [--languages en-GB,es-MX,ja-JP] [--check-hreflang]
@@ -301,8 +302,8 @@ function service(args) {
 
 function seo(args) {
   const command = args[0];
-  const scripts = { performance: "maggie_performance.py", images: "maggie_images.py", sitemap: "maggie_sitemap.py" };
-  if (!scripts[command]) throw new Error("seo command must be performance, images, or sitemap");
+  const scripts = { performance: "maggie_performance.py", images: "maggie_images.py", sitemap: "maggie_sitemap.py", indexnow: "maggie_indexnow.py" };
+  if (!scripts[command]) throw new Error("seo command must be performance, images, sitemap, or indexnow");
   workflowCli(scripts[command], args.slice(1));
 }
 

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

@@ -27,7 +27,7 @@ locale/revision tasks are skipped; failed tasks retry from checkpoints. Run one
 worker per project. Outputs stay draft and non-indexable. Existing host HTTP
 and scheduler integrations still need separate implementation and tests.
 
-Use the stable CLI to initialize a local blog contract, ingest versioned local
+	Use the stable CLI to initialize a local blog contract, ingest versioned local
 content, validate lifecycle invariants, publish with an actor and reason, and
 generate route/feed artifacts. Read the host framework and database contract
 before adding public routes. The host project owns rendering, persistence
@@ -35,19 +35,23 @@ credentials, and deployment; this skill owns normalized blog semantics.
 
 ```bash
 maggie blog init --project . --base-path /our-blogs --confirm
-maggie blog ingest --project . --source local --input content/posts.json --confirm
-maggie blog validate --project .
-maggie blog publish --project . --slug example-post --actor owner --reason "approved" --confirm
+	maggie blog ingest --project . --source local --input content/posts.json --confirm
+	maggie blog validate --project .
+	maggie blog check-gate --project .
+	maggie blog approve --project . --slug example-post --actor reviewer --reason "reviewed" --confirm
+	maggie blog publish --project . --slug example-post --actor owner --reason "approved" --confirm
 maggie blog sitemap --project .
 maggie blog settings --project .
 maggie blog rollback --project . --confirm
 ```
 
-Posts are draft-first. Stable `contentId` is the ingest identity and a
-published slug must not change during a rewrite. Search/sort views are not
-indexable; drafts never appear in public routes, RSS, or sitemap output.
-Provider keys remain server-side. Public publication and migrations always
-require explicit confirmation.
+Posts are draft-first. `maggie blog check-gate` reports the publication policy;
+the default requires `requireReview=true`, disables auto-publish, and forces an
+explicit `approve` transition before `publish`. Stable `contentId` is the
+ingest identity and a published slug must not change during a rewrite.
+Search/sort views are not indexable; drafts never appear in public routes, RSS,
+or sitemap output. Provider keys remain server-side. Public publication and
+migrations always require explicit confirmation.
 
 To initialize native front-end pages from the approved local UI guideline,
 run `maggie-design`:

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

@@ -200,10 +200,25 @@ maggie dash sections bindings-validate --sections-file .maggie/sections.json \
   --references-file .maggie/reference-inventory.json
 maggie dash sections idempotency-validate --contract-file .maggie/reconcile-contract.json
 
-# Classify every published page exactly once:
-maggie dash inventory --pages-file .maggie/published-pages.json
+# Validate API body/response shapes before a client writes against an endpoint:
+maggie dash api-contract --spec .maggie/openapi.json
+
+# Classify every published page exactly once. `pageKind` describes the public
+# page family; `kind`/`rendererKind` describes how it is rendered. Keep these
+# axes separate and require explicit source coverage when database rows do not
+# contain code-rendered routes:
+maggie dash inventory --pages-file .maggie/published-pages.json \
+  --require-page-kinds --require-source-coverage
 ```
 
+The API contract checker fails closed when a body or 2xx response schema is
+missing. Intentional empty bodies must be explicit (`x-maggie-empty-request-body`
+or `x-maggie-empty-response`) so a consumer does not guess field names.
+Inventory reports `pageKindCounts` for service, variant, category hub,
+ordinary, and blog routes, plus `sourceCoverage`. A host adapter must include
+code-rendered routes in the input or declare coverage incomplete; a zero
+database-row count is not evidence that no public routes exist.
+
 The catalogue declares purpose, usage, placement, repeatability and layout
 limits, renderer-owned examples, and the shape of repeated entries. A repeat
 may contain an object (`title`, `body`, `href`, and so on), not just a count;

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

@@ -59,6 +59,11 @@ If the change date is unknown, omit `lastmod`. An empty content-type does not
 need a sitemap chunk in the sitemap index; serving an empty endpoint and
 advertising it are separate decisions.
 
+Validation also reports a freshness-distribution warning when a large sample
+collapses onto one date (especially today). Treat that as a provenance review,
+not as a reason to rewrite dates: verify the content-change event and omit
+unknown dates. Strict semantic validation promotes the warning to a failure.
+
 Generated sitemap XML uses the conventional readable shape by default: one
 `<url>`/`<sitemap>` entry per block, UTF-8 XML, and date-only `lastmod` evidence
 rendered as a full UTC W3C datetime. The plan also exposes the response
@@ -174,6 +179,15 @@ maggie seo sitemap validate --plan docs/sitemap-plan.json
 # After an approved host adapter apply, rollback uses its exact backup manifest.
 maggie seo sitemap rollback --backup-manifest .maggie-sitemap-backups/<plan>/backup-manifest.json \
   --public-dir public --confirm
+
+# Change-driven IndexNow: only pass URLs whose rendered content changed.
+maggie seo indexnow key-check --public-dir public --key-file <key>.txt --key <key>
+maggie seo indexnow plan --origin https://example.com \
+  --changed-urls-file .maggie/changed-urls.json \
+  --state-file .maggie/indexnow-state.json --key <key> \
+  --output .maggie/indexnow-plan.json
+maggie seo indexnow submit --plan .maggie/indexnow-plan.json \
+  --state-file .maggie/indexnow-state.json --confirm
 ```
 
 Only confirmed image variants may enter `srcset`; `apply` requires an explicit
@@ -182,6 +196,13 @@ omit empty chunks from the sitemap index, enforce absolute same-origin URLs, and
 record redirects for removed sitemap files. Read the [image and sitemap PRD](https://github.com/TOPY-AI-LTD/ai-cmo-skills/blob/main/docs/image-sitemap-structure-prd.md)
 for adapter and rollback rules.
 
+IndexNow is opt-in and complements, rather than replaces, the sitemap. The
+host supplies a changed-URL set and a public verification-key file. The plan
+holds back URLs accepted within 24 hours, deduplicates same-origin URLs, and
+records accepted state only after HTTP 200/202. A 403/429/5xx or network error
+is retryable and must never make the editor save fail; do not retry unchanged
+URLs in a loop.
+
 For a deterministic technical smoke check, run:
 
 ```bash

package/bundled-tools/clis/maggie_blog.py

@@ -27,6 +27,8 @@ def main() -> int:
     inspect = sub.add_parser("inspect"); inspect.add_argument("--project", type=Path, default=Path.cwd())
     ingest = sub.add_parser("ingest"); ingest.add_argument("--project", type=Path, default=Path.cwd()); ingest.add_argument("--input", type=Path, required=True); ingest.add_argument("--source", default="local"); ingest.add_argument("--confirm", action="store_true")
     validate = sub.add_parser("validate"); validate.add_argument("--project", type=Path, default=Path.cwd())
+    gate = sub.add_parser("check-gate", help="report whether generated content requires review before publication"); gate.add_argument("--project", type=Path, default=Path.cwd())
+    approve = sub.add_parser("approve"); approve.add_argument("--project", type=Path, default=Path.cwd()); approve.add_argument("--slug", required=True); approve.add_argument("--actor", required=True); approve.add_argument("--reason", required=True); approve.add_argument("--confirm", action="store_true")
     publish = sub.add_parser("publish"); publish.add_argument("--project", type=Path, default=Path.cwd()); publish.add_argument("--slug", required=True); publish.add_argument("--actor", required=True); publish.add_argument("--reason", required=True); publish.add_argument("--confirm", action="store_true")
     sitemap = sub.add_parser("sitemap"); sitemap.add_argument("--project", type=Path, default=Path.cwd())
     settings = sub.add_parser("settings"); settings.add_argument("--project", type=Path, default=Path.cwd())
@@ -38,7 +40,7 @@ def main() -> int:
         print(json.dumps(result, indent=2, ensure_ascii=False))
         return 0 if result["status"] != "error" else 1
     store = BlogStore(args.project.resolve())
-    if args.command in {"init", "ingest", "publish", "rollback", "translate-pending"} and not args.confirm:
+    if args.command in {"init", "ingest", "publish", "approve", "rollback", "translate-pending"} and not args.confirm:
         print("CONFIRMATION_REQUIRED: rerun with --confirm", file=sys.stderr); return 2
     try:
         if args.command == "init": result = store.init(args.base_path, args.posts_per_page)
@@ -51,6 +53,8 @@ def main() -> int:
             if not isinstance(payload, list): raise ValueError("local input must be a JSON array")
             result = store.ingest(payload, args.source)
         elif args.command == "validate": result = store.validate()
+        elif args.command == "check-gate": result = store.review_gate(store.settings())
+        elif args.command == "approve": result = store.approve(args.slug, args.actor, args.reason)
         elif args.command == "publish": result = store.publish(args.slug, args.actor, args.reason)
         elif args.command == "settings": result = store.settings()
         elif args.command == "rollback": result = store.rollback(args.backup)

package/bundled-tools/clis/maggie_dash.py

@@ -25,6 +25,7 @@ from service_variants import ServiceVariantStore  # noqa: E402
 from maggie_dash_ui import load_and_validate  # noqa: E402
 from maggie_sections import catalogue, remap_translations, section_id_migration, validate_registry, copy_notes, validate_values, validate_fanout, reconcile_fields, validate_locale_coverage  # noqa: E402
 from maggie_quality import validate_variant_copy, validate_media_uniqueness, classify_inventory, validate_bindings, validate_reconcile_contract  # noqa: E402
+from maggie_api_contract import validate_api_contract  # noqa: E402
 from route_imports import classify_bindings  # noqa: E402
 
 
@@ -422,7 +423,14 @@ def command_components_audit(args: argparse.Namespace) -> int:
 def command_inventory(args: argparse.Namespace) -> int:
     """Classify each published page once, with no broad predicate overlap."""
     value = json.loads(Path(args.pages_file).resolve().read_text(encoding="utf-8"))
-    result = classify_inventory(value)
+    result = classify_inventory(value, require_page_kinds=args.require_page_kinds, require_source_coverage=args.require_source_coverage)
+    emit(result)
+    return 0 if result["passed"] else 1
+
+
+def command_api_contract(args: argparse.Namespace) -> int:
+    value = json.loads(Path(args.spec).resolve().read_text(encoding="utf-8"))
+    result = validate_api_contract(value)
     emit(result)
     return 0 if result["passed"] else 1
 
@@ -572,7 +580,12 @@ def parser() -> argparse.ArgumentParser:
     components.set_defaults(func=command_components_audit)
     inventory = sub.add_parser("inventory", help="classify published pages into disjoint band/code-rendered kinds")
     inventory.add_argument("--pages-file", required=True, help="JSON page inventory")
+    inventory.add_argument("--require-page-kinds", action="store_true", help="fail when a published page has no pageKind")
+    inventory.add_argument("--require-source-coverage", action="store_true", help="fail unless sourceCoverage.complete is true")
     inventory.set_defaults(func=command_inventory)
+    api_contract = sub.add_parser("api-contract", help="validate declared request and success-response schemas")
+    api_contract.add_argument("--spec", required=True, help="OpenAPI-like JSON document")
+    api_contract.set_defaults(func=command_api_contract)
     variant = sub.add_parser("variant", help="manage service variant lifecycle")
     variant_sub = variant.add_subparsers(dest="variant_command", required=True)
     create = variant_sub.add_parser("create"); create.add_argument("--project", default="."); create.add_argument("--service-id", required=True); create.add_argument("--variant-id", required=True); create.add_argument("--variant-type", required=True); create.add_argument("--locale", required=True); create.add_argument("--market", required=True); create.add_argument("--slug", required=True); create.add_argument("--title", required=True); create.add_argument("--facts", required=True); create.add_argument("--source-revision", required=True); create.add_argument("--canonical-variant-id"); create.add_argument("--cluster-link", action="append", default=[]); create.add_argument("--layout-family", default="service-default"); create.add_argument("--confirm", action="store_true")

package/bundled-tools/clis/maggie_indexnow.py

@@ -0,0 +1,60 @@
+#!/usr/bin/env python3
+"""Plan and submit change-driven IndexNow notifications."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+import sys
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "runtime"))
+from maggie_indexnow import check_key_file, plan_indexnow, submit_plan  # noqa: E402
+
+
+def read_json(path: Path, default: object) -> object:
+    if not path.exists():
+        return default
+    return json.loads(path.read_text(encoding="utf-8"))
+
+
+def write_json(path: Path, value: object) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(value, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(prog="maggie seo indexnow")
+    sub = parser.add_subparsers(dest="command", required=True)
+    key_check = sub.add_parser("key-check", help="verify the public ownership key file")
+    key_check.add_argument("--public-dir", required=True); key_check.add_argument("--key-file", required=True); key_check.add_argument("--key", required=True)
+    plan = sub.add_parser("plan", help="hold back recently accepted URLs and create a submission plan")
+    plan.add_argument("--origin", required=True); plan.add_argument("--changed-urls-file", required=True); plan.add_argument("--state-file", required=True); plan.add_argument("--key", required=True); plan.add_argument("--key-location"); plan.add_argument("--guard-hours", type=int, default=24); plan.add_argument("--now"); plan.add_argument("--output", required=True)
+    submit = sub.add_parser("submit", help="submit an approved plan; provider failure never updates accepted state")
+    submit.add_argument("--plan", required=True); submit.add_argument("--state-file", required=True); submit.add_argument("--endpoint", default="https://api.indexnow.org/indexnow"); submit.add_argument("--confirm", action="store_true")
+    args = parser.parse_args()
+    try:
+        if args.command == "key-check":
+            result = check_key_file(Path(args.public_dir).resolve(), args.key_file, args.key)
+            print(json.dumps(result, indent=2)); return 0 if result["status"] == "pass" else 1
+        if args.command == "plan":
+            changed = read_json(Path(args.changed_urls_file), [])
+            urls = changed.get("urls", []) if isinstance(changed, dict) else changed
+            if not isinstance(urls, list): raise ValueError("changed-urls-file must be a JSON array or {\"urls\": []}")
+            result = plan_indexnow(args.origin, urls, read_json(Path(args.state_file), {}), key=args.key, key_location=args.key_location, guard_hours=args.guard_hours, now=args.now)
+            write_json(Path(args.output), result)
+            print(json.dumps({"status": "planned", "eligible": len(result["eligible"]), "heldBack": len(result["heldBack"]), "rejected": len(result["rejected"]), "output": str(Path(args.output).resolve())}, indent=2)); return 0
+        if not args.confirm: raise ValueError("submit requires --confirm")
+        plan_value = read_json(Path(args.plan), {})
+        if not isinstance(plan_value, dict) or plan_value.get("schemaVersion") != "maggie-indexnow.v1": raise ValueError("invalid IndexNow plan")
+        state_path = Path(args.state_file); state = read_json(state_path, {})
+        if not isinstance(state, dict): state = {}
+        result = submit_plan(plan_value, state, args.endpoint)
+        if result["status"] == "accepted": write_json(state_path, state)
+        print(json.dumps(result, indent=2)); return 0 if result["status"] in {"accepted", "no-op"} else 1
+    except (OSError, ValueError, TypeError, json.JSONDecodeError) as error:
+        print(f"maggie-indexnow: {error}", file=sys.stderr); return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/bundled-tools/runtime/maggie_api_contract.py

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

package/bundled-tools/runtime/maggie_blog.py

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

package/bundled-tools/runtime/maggie_indexnow.py

@@ -0,0 +1,128 @@
+"""Provider-neutral, change-driven IndexNow planning and submission state."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+from typing import Any
+from urllib.error import HTTPError, URLError
+from urllib.parse import urlparse
+from urllib.request import Request, urlopen
+
+
+SCHEMA = "maggie-indexnow.v1"
+DEFAULT_GUARD_HOURS = 24
+ACCEPTED = {200, 202}
+
+
+def _now(value: str | None = None) -> datetime:
+    if value:
+        return datetime.fromisoformat(value.replace("Z", "+00:00")).astimezone(timezone.utc)
+    return datetime.now(timezone.utc)
+
+
+def _iso(value: datetime) -> str:
+    return value.astimezone(timezone.utc).isoformat(timespec="seconds").replace("+00:00", "Z")
+
+
+def normalise_urls(origin: str, urls: list[object]) -> tuple[list[str], list[str]]:
+    """Return valid same-origin URLs and explicit rejects."""
+    base = origin.rstrip("/")
+    origin_host = urlparse(base).netloc
+    accepted: set[str] = set()
+    rejected: list[str] = []
+    for raw in urls:
+        value = str(raw or "").strip()
+        if not value:
+            continue
+        candidate = value if value.startswith(("http://", "https://")) else f"{base}/{value.lstrip('/')}"
+        parsed = urlparse(candidate)
+        if parsed.scheme not in {"http", "https"} or parsed.netloc != origin_host or parsed.fragment:
+            rejected.append(value)
+            continue
+        accepted.add(candidate)
+    return sorted(accepted), rejected
+
+
+def _state_entries(state: object) -> list[dict[str, Any]]:
+    if not isinstance(state, dict) or not isinstance(state.get("submissions"), list):
+        return []
+    return [item for item in state["submissions"] if isinstance(item, dict)]
+
+
+def plan_indexnow(origin: str, urls: list[object], state: object | None = None,
+                  *, key: str, key_location: str | None = None,
+                  guard_hours: int = DEFAULT_GUARD_HOURS, now: str | None = None) -> dict[str, Any]:
+    if not key.strip():
+        raise ValueError("IndexNow key is required; it is a public ownership key, not a provider secret")
+    eligible, rejected = normalise_urls(origin, urls)
+    cutoff = _now(now) - timedelta(hours=guard_hours)
+    accepted_at: dict[str, datetime] = {}
+    for entry in _state_entries(state):
+        if entry.get("statusCode") not in ACCEPTED or not entry.get("acceptedAt"):
+            continue
+        try:
+            stamp = _now(str(entry["acceptedAt"]))
+        except ValueError:
+            continue
+        if stamp >= cutoff:
+            accepted_at[str(entry.get("url"))] = stamp
+    held_back = [{"url": url, "acceptedAt": _iso(accepted_at[url]), "reason": f"accepted within {guard_hours} hours"}
+                 for url in eligible if url in accepted_at]
+    held_set = {item["url"] for item in held_back}
+    return {
+        "schemaVersion": SCHEMA,
+        "origin": origin.rstrip("/"),
+        "key": key.strip(),
+        "keyLocation": key_location or f"{origin.rstrip('/')}/{key.strip()}.txt",
+        "guardHours": guard_hours,
+        "eligible": [url for url in eligible if url not in held_set],
+        "heldBack": held_back,
+        "rejected": rejected,
+        "verification": {"required": True, "status": "not-checked"},
+        "plannedAt": _iso(_now(now)),
+        "mutation": False,
+    }
+
+
+def check_key_file(public_dir: Path, key_file: str, key: str) -> dict[str, Any]:
+    if not key.strip():
+        raise ValueError("key is required")
+    relative = Path(key_file)
+    if relative.is_absolute() or ".." in relative.parts or len(relative.parts) != 1:
+        raise ValueError("key file must be a single filename inside public-dir")
+    target = public_dir / relative
+    served = target.read_text(encoding="utf-8").strip() if target.exists() else None
+    return {"schemaVersion": SCHEMA, "path": str(relative), "exists": target.exists(),
+            "matches": served == key.strip(), "status": "pass" if served == key.strip() else "fail"}
+
+
+def submit_plan(plan: dict[str, Any], state: dict[str, Any], endpoint: str) -> dict[str, Any]:
+    urls = plan.get("eligible") if isinstance(plan.get("eligible"), list) else []
+    if not urls:
+        return {"schemaVersion": SCHEMA, "status": "no-op", "submitted": 0, "accepted": 0, "retryable": False, "mutation": True}
+    payload = {"host": urlparse(str(plan["origin"])).netloc, "key": str(plan["key"]),
+               "keyLocation": str(plan["keyLocation"]), "urlList": urls}
+    status_code: int | None = None
+    failure = None
+    try:
+        request = Request(endpoint, data=json.dumps(payload).encode("utf-8"), headers={"Content-Type": "application/json; charset=utf-8"}, method="POST")
+        with urlopen(request, timeout=30) as response:
+            status_code = int(response.status)
+    except HTTPError as error:
+        status_code = int(error.code)
+        failure = "provider returned HTTP status"
+    except (URLError, TimeoutError, OSError):
+        failure = "provider request failed"
+    accepted = status_code in ACCEPTED
+    retryable = status_code in {403, 429} or (status_code is not None and status_code >= 500) or failure is not None
+    entries = _state_entries(state)
+    if accepted:
+        stamp = _iso(_now())
+        entries.extend({"url": url, "statusCode": status_code, "acceptedAt": stamp, "batchId": hashlib.sha256((stamp + url).encode()).hexdigest()[:12]} for url in urls)
+    state.update({"schemaVersion": SCHEMA, "submissions": entries})
+    return {"schemaVersion": SCHEMA, "status": "accepted" if accepted else "retryable-failure" if retryable else "failed",
+            "submitted": len(urls), "accepted": len(urls) if accepted else 0, "statusCode": status_code,
+            "retryable": retryable, "failure": failure, "mutation": True}

package/bundled-tools/runtime/maggie_quality.py

@@ -14,6 +14,7 @@ MEDIA_SCHEMA = "maggie-media-uniqueness.v1"
 INVENTORY_SCHEMA = "maggie-page-inventory.v1"
 BINDING_SCHEMA = "maggie-section-bindings.v1"
 IDEMPOTENCY_SCHEMA = "maggie-reconcile-contract.v1"
+PAGE_KINDS = {"service", "variant", "category-hub", "ordinary", "blog-topic", "blog-archive", "blog-article", "homepage", "service-index", "service-category", "redirect", "asset"}
 
 
 def _items(value: object, *keys: str) -> list[dict[str, Any]]:
@@ -116,8 +117,10 @@ def validate_media_uniqueness(value: object, *, across_siblings: bool = False) -
     return {"schemaVersion": MEDIA_SCHEMA, "passed": not errors, "duplicates": errors, "pages": len(pages), "acrossSiblings": across_siblings}
 
 
-def classify_inventory(value: object) -> dict[str, Any]:
+def classify_inventory(value: object, *, require_page_kinds: bool = False, require_source_coverage: bool = False) -> dict[str, Any]:
     pages = _items(value, "pages", "items", "routes")
+    if isinstance(value, dict):
+        pages += _items(value, "codeRenderedPages", "codeRenderedRoutes")
     allowed = {"band", "code-rendered", "redirect", "asset", "unknown"}
     records: list[dict[str, Any]] = []
     errors: list[str] = []
@@ -127,7 +130,7 @@ def classify_inventory(value: object) -> dict[str, Any]:
         if path in seen:
             errors.append(f"duplicate inventory path: {path}")
         seen.add(path)
-        explicit = str(page.get("kind") or page.get("classification") or "").casefold()
+        explicit = str(page.get("rendererKind") or page.get("rendering") or page.get("kind") or page.get("classification") or "").casefold()
         if explicit in {"code", "code-rendered", "component", "source"}:
             kind = "code-rendered"
         elif explicit in {"band", "section", "sections"}:
@@ -140,11 +143,25 @@ def classify_inventory(value: object) -> dict[str, Any]:
             kind = "code-rendered"
         else:
             kind = "unknown"
-        records.append({"path": path, "kind": kind})
+        raw_page_kind = page.get("pageKind") or page.get("pageType")
+        if not raw_page_kind and str(page.get("kind") or "").casefold() in PAGE_KINDS:
+            raw_page_kind = page.get("kind")
+        page_kind = str(raw_page_kind or "").casefold().replace("_", "-")
+        records.append({"path": path, "kind": kind, "pageKind": page_kind or None})
         if kind not in allowed or kind == "unknown":
             errors.append(f"{path}: cannot classify published page")
+        if page_kind and page_kind not in PAGE_KINDS:
+            errors.append(f"{path}: unknown pageKind {page_kind}")
+        if require_page_kinds and not page_kind:
+            errors.append(f"{path}: pageKind is required")
     counts = dict(sorted(Counter(item["kind"] for item in records).items()))
-    return {"schemaVersion": INVENTORY_SCHEMA, "passed": not errors and len(records) == len(seen), "records": records, "counts": counts, "bandCount": counts.get("band", 0), "codeRenderedCount": counts.get("code-rendered", 0), "errors": errors, "disjoint": True}
+    page_kind_counts = dict(sorted(Counter(item["pageKind"] for item in records if item["pageKind"]).items()))
+    coverage = value.get("sourceCoverage") if isinstance(value, dict) else None
+    if not isinstance(coverage, dict):
+        coverage = {"status": "unverified", "complete": False, "sources": []}
+    if require_source_coverage and coverage.get("complete") is not True:
+        errors.append("sourceCoverage.complete must be true when source coverage is required")
+    return {"schemaVersion": INVENTORY_SCHEMA, "passed": not errors and len(records) == len(seen), "records": records, "counts": counts, "pageKindCounts": page_kind_counts, "pageKinds": sorted(PAGE_KINDS), "bandCount": counts.get("band", 0), "codeRenderedCount": counts.get("code-rendered", 0), "errors": errors, "disjoint": True, "sourceCoverage": coverage}
 
 
 def _reference_values(references: object) -> dict[str, set[str]]:

package/bundled-tools/runtime/maggie_sitemap.py

@@ -15,6 +15,8 @@ HARD_BYTES_LIMIT = 52_428_800
 DEFAULT_CHUNK_TARGET = 500
 EXCLUDED_PATHS = re.compile(r"/(search|find|login|draft|preview)(/|$)", re.I)
 W3C_UTC_DATETIME = re.compile(r"^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$")
+FRESHNESS_MIN_SAMPLE = 10
+FRESHNESS_CONCENTRATION_THRESHOLD = 0.75
 
 
 def absolute_url(url: str, origin: str) -> bool:
@@ -100,6 +102,51 @@ def xml_file(urls: list[dict[str, str]]) -> str:
     return '<?xml version="1.0" encoding="UTF-8"?>\n<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9" xmlns:xhtml="http://www.w3.org/1999/xhtml">\n' + body + ('\n' if body else '') + '</urlset>\n'
 
 
+def freshness_report(routes: list[dict[str, str]], today: str | None = None) -> dict[str, object]:
+    """Detect a suspiciously uniform lastmod distribution.
+
+    A structurally valid sitemap can still lose crawler trust when a migration
+    stamps nearly every URL with the same operational date. This is a warning
+    by default so unknown or intentionally batched content is not silently
+    rewritten; strict semantic validation promotes it to an error.
+    """
+    dates: list[str] = []
+    for route in routes:
+        value = route.get("lastmod")
+        if not value:
+            continue
+        normalised = conventional_lastmod(str(value))
+        if W3C_UTC_DATETIME.fullmatch(normalised):
+            dates.append(normalised[:10])
+    counts: dict[str, int] = {}
+    for date in dates:
+        counts[date] = counts.get(date, 0) + 1
+    dominant_date, dominant_count = (max(counts.items(), key=lambda item: (item[1], item[0]))
+                                     if counts else (None, 0))
+    sample = len(dates)
+    ratio = dominant_count / sample if sample else 0.0
+    current = today or datetime.now(timezone.utc).date().isoformat()
+    suspicious = bool(sample >= FRESHNESS_MIN_SAMPLE and ratio >= FRESHNESS_CONCENTRATION_THRESHOLD)
+    warnings: list[str] = []
+    if suspicious:
+        date_label = "today's date" if dominant_date == current else str(dominant_date)
+        warnings.append(
+            f"lastmod distribution is concentrated on {date_label} "
+            f"({dominant_count}/{sample}, {ratio:.0%}); verify content-change provenance"
+        )
+    return {
+        "status": "warn" if warnings else "pass",
+        "datedRoutes": sample,
+        "distinctDates": len(counts),
+        "dominantDate": dominant_date,
+        "dominantCount": dominant_count,
+        "dominantRatio": round(ratio, 4),
+        "today": current,
+        "todayCount": counts.get(current, 0),
+        "warnings": warnings,
+    }
+
+
 def build_plan(routes: list[dict[str, str]], origin: str, content_types: set[str], chunk_target: int = DEFAULT_CHUNK_TARGET, previous: dict | None = None) -> dict:
     if chunk_target < 1 or chunk_target > HARD_URL_LIMIT:
         raise ValueError("chunk target must be between 1 and 50000")
@@ -134,6 +181,7 @@ def validate_plan_data(plan: dict, strict_semantic: bool = False) -> dict:
     if not urlparse(origin).scheme or not urlparse(origin).netloc:
         errors.append("origin must be an absolute HTTP(S) URL")
     expected_urls = []
+    all_routes: list[dict[str, str]] = []
     for group in plan.get("groups", []):
         for chunk in group.get("chunks", []):
             expected_urls.append(chunk.get("url"))
@@ -142,6 +190,7 @@ def validate_plan_data(plan: dict, strict_semantic: bool = False) -> dict:
             if chunk.get("bytes", 0) > HARD_BYTES_LIMIT:
                 errors.append(f"chunk exceeds byte limit: {chunk.get('filename')}")
             for route in chunk.get("routes", []):
+                all_routes.append(route)
                 if route.get("indexable") is False or route.get("searchable") is False:
                     errors.append(f"non-indexable/searchable route was emitted: {route.get('url')}")
                 if route.get("canonicalUrl") and route.get("canonicalUrl") != route.get("url"):
@@ -187,6 +236,8 @@ def validate_plan_data(plan: dict, strict_semantic: bool = False) -> dict:
         errors.append("sitemap index is not valid XML")
     if not expected_urls:
         warnings.append("no sitemap chunks generated; empty content types are not advertised")
+    freshness = freshness_report(all_routes)
+    warnings.extend(freshness["warnings"])
     if strict_semantic:
         for group in plan.get("groups", []):
             for chunk in group.get("chunks", []):
@@ -195,7 +246,7 @@ def validate_plan_data(plan: dict, strict_semantic: bool = False) -> dict:
                     if "contentWords" not in route: warnings.append(f"semantic content evidence missing: {route.get('url')}")
         if warnings:
             errors.extend(warnings)
-    return {"status": "pass" if not errors else "fail", "errors": errors, "warnings": warnings}
+    return {"status": "pass" if not errors else "fail", "errors": errors, "warnings": warnings, "freshness": freshness}
 
 
 def agent_files(routes: list[dict[str, str]], origin: str, locale: str = "en") -> dict[str, str]:

package/package.json

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