@rubytech/create-maxy-code 0.1.62 → 0.1.63

package/payload/platform/plugins/preval/skills/property-preval/references/render.py

@@ -5,7 +5,9 @@ derived from one inputs.json (shape: template-inputs.schema.json), drives
 Chrome headless to produce a 5-page A4 PDF, and asserts page count == 5.
 
 Fails loud on any missing / unverifiable load-bearing input. No silent
-fallback modes — see _assert_inputs.
+fallback modes — see _assert_inputs. Task 157 layers provenance gates
+(market_summary.origin, agent_listings[].origin, agent_overrides) on top
+of 156's load-bearing-input checks.
 
 Usage:
     python3 render.py inputs.json
@@ -217,9 +219,11 @@ def _agent_listings_cards(rows: list[dict], out_dir: Path) -> str:
 def _valuation_block(subject: dict, valuation: dict) -> str:
     """Build the page-2 valuation panel: headline range, adjustments, final range.
 
-    sqft is asserted non-null upstream by _assert_inputs — no fallback panel here.
+    The three EPC certificate fields are asserted non-null upstream by
+    _assert_inputs — no fallback panel here. sqft is derived from
+    total_floor_area_m2 via M2_TO_SQFT.
     """
-    sqft = subject["sqft"]
+    sqft = _derived_sqft(subject)
     low_psf  = valuation["sold_psf_low"]
     mid_psf  = valuation["sold_psf"]
     high_psf = valuation["sold_psf_high"]
@@ -268,25 +272,20 @@ def _valuation_block(subject: dict, valuation: dict) -> str:
     return '<div class="val-panel">' + "".join(rows) + "</div>" + final
 
 
+def _derived_sqft(subject: dict) -> int:
+    return round(float(subject["total_floor_area_m2"]) * M2_TO_SQFT)
+
+
 def _kpi_subject_sqft(subject: dict) -> tuple[str, str]:
-    sqft = subject["sqft"]
-    m2 = subject.get("sqft_m2")
-    sub = f"≈ {m2:.0f} m² · from EPC register" if m2 else "Square feet (operator)"
-    return f"{int(sqft):,}", sub
+    sqft = _derived_sqft(subject)
+    m2 = float(subject["total_floor_area_m2"])
+    return f"{sqft:,}", f"≈ {m2:.0f} m² · from EPC certificate"
 
 
 def _kpi_subject_epc(subject: dict) -> tuple[str, str]:
-    current  = subject.get("epc_current")
-    potential = subject.get("epc_potential")
-    lodgement = subject.get("epc_lodgement")
-    if not current:
-        return "—", "No EPC on file"
-    sub_bits = []
-    if potential:
-        sub_bits.append(f"potential {potential}")
-    if lodgement:
-        sub_bits.append(f"lodged {lodgement}")
-    return current, " · ".join(sub_bits) or "EPC register"
+    current  = subject["current_energy_rating"]
+    lodgement = subject["lodgement_date"]
+    return current, f"lodged {lodgement}"
 
 
 # ---------------- input assertions ----------------
@@ -303,6 +302,30 @@ class PrevalAbort(RuntimeError):
         self.hint = hint
 
 
+_STREET_TOKEN_STOPWORDS = {
+    "the", "a", "an", "of", "and",
+    "road", "street", "drive", "lane", "avenue", "close", "court",
+    "place", "way", "gardens", "crescent", "hill", "rise", "grove",
+    "terrace", "mews", "square", "park", "walk", "row",
+    "rd", "st", "dr", "ln", "ave", "cl", "ct", "pl",
+}
+
+
+def _street_token(address: str) -> str | None:
+    """First non-stopword token from the address's street component.
+
+    Used to detect cover_hero photos sourced from a sister property folder.
+    "9 Phoenix Drive, Bishop's Stortford, CM23 2UJ" → "phoenix".
+    """
+    if not address:
+        return None
+    first = address.split(",")[0].strip().lower()
+    for raw in re.split(r"[^a-z]+", first):
+        if raw and not raw.isdigit() and raw not in _STREET_TOKEN_STOPWORDS:
+            return raw
+    return None
+
+
 def _assert_path_image(path_str: str, min_w: int = 1200, min_h: int = 800) -> None:
     """Existence + dimension check. Symlinks pointing into another property's
     folder are rejected (cover-hero cross-contamination guard)."""
@@ -316,12 +339,10 @@ def _assert_path_image(path_str: str, min_w: int = 1200, min_h: int = 800) -> No
         target = p.resolve()
         parts = target.parts
         if "properties" in parts:
-            # symlink → properties/<other-slug>/… is a cross-contamination
             raise PrevalAbort(
                 "subject-cover-hero-symlinked-foreign",
                 f"cover_hero is a symlink into another property's folder: {target}",
             )
-    # Dimensions. Avoid a Pillow dep; read PNG/JPEG headers directly.
     w, h = _image_dimensions(p)
     if w is None or h is None:
         raise PrevalAbort(
@@ -343,7 +364,6 @@ def _image_dimensions(p: Path) -> tuple[int | None, int | None]:
             if len(head) < 24:
                 return None, None
             if head[:8] == b"\x89PNG\r\n\x1a\n":
-                # IHDR width/height at bytes 16..24, big-endian uint32.
                 w = int.from_bytes(head[16:20], "big")
                 h = int.from_bytes(head[20:24], "big")
                 return w, h
@@ -357,7 +377,7 @@ def _image_dimensions(p: Path) -> tuple[int | None, int | None]:
                     if not marker:
                         return None, None
                     if 0xC0 <= marker[0] <= 0xCF and marker[0] not in (0xC4, 0xC8, 0xCC):
-                        f.read(3)  # length(2) + precision(1)
+                        f.read(3)
                         h = int.from_bytes(f.read(2), "big")
                         w = int.from_bytes(f.read(2), "big")
                         return w, h
@@ -371,23 +391,36 @@ def _image_dimensions(p: Path) -> tuple[int | None, int | None]:
 def _assert_inputs(inputs: dict) -> None:
     """Fail loud on any missing or unverifiable load-bearing input.
 
-    Raises PrevalAbort with a named cause. No silent fallback paths.
+    Task 156 causes (load-bearing inputs):
+      subject-cover-hero-*, brand-unresolved,
+      agent-listings-empty, market-summary-too-thin.
+
+    Task 157 causes (provenance — agent didn't invent the input):
+      cover-hero-not-subject, agent-listings-invented,
+      market-summary-invented, brand-invented.
+
+    Task 163 cause (EPC certificate paste-in completes 157's mandate):
+      epc-certificate-not-supplied — any of total_floor_area_m2,
+      current_energy_rating, lodgement_date is null/missing.
     """
     subject = inputs.get("subject") or {}
+    address = inputs.get("address") or ""
+    overrides = inputs.get("agent_overrides") or {}
 
-    # subject.sqft / sqft_m2 — required, non-null integers.
-    if not subject.get("sqft"):
-        raise PrevalAbort(
-            "subject-sqft-missing",
-            "subject.sqft is null — run epc-key-register and re-derive, or paste subject.sqft as an operator override before invocation.",
-        )
-    if not subject.get("sqft_m2"):
+    # --- 163: EPC certificate fields are operator paste-in ---
+    missing_epc = [
+        f for f in ("total_floor_area_m2", "current_energy_rating", "lodgement_date")
+        if not subject.get(f)
+    ]
+    if missing_epc:
         raise PrevalAbort(
-            "subject-sqft-m2-missing",
-            "subject.sqft_m2 is null — the EPC m² figure must be supplied alongside sqft.",
+            "epc-certificate-not-supplied",
+            f"subject is missing EPC certificate field(s) {missing_epc}. "
+            "Paste total_floor_area_m2, current_energy_rating, and lodgement_date "
+            "from the EPC certificate into subject before re-invoking. "
+            "No mid-run prompt — the operator supplies the certificate before invocation.",
         )
 
-    # subject.cover_hero — required, exists, ≥ 1200×800, not symlinked into another property's folder.
     hero = subject.get("cover_hero")
     if not hero:
         raise PrevalAbort(
@@ -397,7 +430,6 @@ def _assert_inputs(inputs: dict) -> None:
     if not hero.startswith(("http://", "https://", "data:")):
         _assert_path_image(hero)
 
-    # brand — must be the resolved DESIGN.md object, not a stub.
     brand = inputs.get("brand") or {}
     required_brand = ("name", "tagline", "primary", "primary_dark", "accent", "paper", "paper_banded", "rule")
     missing_brand = [k for k in required_brand if not brand.get(k)]
@@ -407,21 +439,73 @@ def _assert_inputs(inputs: dict) -> None:
             f"brand is missing required token(s) {missing_brand} — resolve from the agent's on-disk DESIGN.md before invocation.",
         )
 
-    # agent_listings — non-empty.
     if not inputs.get("agent_listings"):
         raise PrevalAbort(
             "agent-listings-empty",
             "agent_listings is empty — paste at least one recent listing for the closing page.",
         )
 
-    # market_summary.paragraphs — at least 2.
-    paras = (inputs.get("market_summary") or {}).get("paragraphs") or []
+    ms = inputs.get("market_summary") or {}
+    paras = ms.get("paragraphs") or []
     if len(paras) < 2:
         raise PrevalAbort(
             "market-summary-too-thin",
             f"market_summary.paragraphs has {len(paras)} entries — minimum 2.",
         )
 
+    # --- 157: provenance gates ---
+    if hero and not hero.startswith(("http://", "https://", "data:")):
+        hero_lc = hero.lower()
+        match = re.search(r"/properties?/([^/]+)/", hero_lc)
+        if match:
+            slug = match.group(1)
+            street = _street_token(address)
+            if street and street not in slug:
+                raise PrevalAbort(
+                    "cover-hero-not-subject",
+                    f"subject.cover_hero ({hero}) sits in a property folder whose "
+                    f"slug ({slug}) does not contain the subject street token "
+                    f"({street}). Prompt the operator for the subject's own photo.",
+                )
+
+    if not overrides.get("listings_status_curated"):
+        for listing in inputs.get("agent_listings") or []:
+            origin = (listing or {}).get("origin")
+            if not origin or origin == "operator":
+                continue
+            src = Path(str(origin)).expanduser()
+            if not src.exists():
+                continue
+            try:
+                source = json.loads(src.read_text())
+            except (OSError, json.JSONDecodeError):
+                continue
+            if source.get("status") in (None, "") and listing.get("status"):
+                raise PrevalAbort(
+                    "agent-listings-invented",
+                    f"agent_listings entry {listing.get('slug')} has status "
+                    f"'{listing['status']}' but source {src} carries status:null. "
+                    "Prompt the operator to confirm each status, then set "
+                    "agent_overrides.listings_status_curated: true.",
+                )
+
+    if ms.get("origin") not in ("operator", "operator-edited-llm-stub"):
+        raise PrevalAbort(
+            "market-summary-invented",
+            "market_summary.origin must be 'operator' or 'operator-edited-llm-stub'. "
+            "Have the operator draft or accept the paragraphs before rendering — "
+            "the agent never invents the market narrative unprompted.",
+        )
+
+    if brand.get("name") and not overrides.get("brand_selected_by_operator"):
+        raise PrevalAbort(
+            "brand-invented",
+            f"brand.name ('{brand['name']}') was set without "
+            "agent_overrides.brand_selected_by_operator: true. Ask the operator "
+            "which estate agent is pitching for this instruction; the presence "
+            "of a DESIGN.md on disk does not authorise selection.",
+        )
+
 
 # ---------------- render ----------------
 
@@ -452,10 +536,9 @@ def render(inputs: dict, out_dir: Path, template_path: Path | None = None) -> Pa
 
     psf = d.get("sales_per_month")
     if psf is None:
-        psf = max(1, round(d["for_sale"] / 7))  # crude fallback only when not provided
+        psf = max(1, round(d["for_sale"] / 7))
 
     slots = {
-        # branding
         "brand_name":         brand["name"],
         "brand_tagline":      brand["tagline"],
         "brand_primary":      brand["primary"],
@@ -467,14 +550,12 @@ def render(inputs: dict, out_dir: Path, template_path: Path | None = None) -> Pa
         "wordmark_light":     _wordmark(brand, "light", out_dir),
         "wordmark_dark":      _wordmark(brand, "dark",  out_dir),
 
-        # cover + header
         "subject_hero_path":  _hero_asset(subject, out_dir),
         "address":            inputs["address"],
         "address_short":      _short_address(inputs["address"]),
         "postcode":           inputs["postcode"],
         "generated":          inputs["generated"],
 
-        # page 2 — subject valuation
         "kpi_subject_sqft":     subject_sqft,
         "kpi_subject_sqft_sub": subject_sqft_sub,
         "kpi_subject_beds":     str(subject.get("beds") or "—"),
@@ -485,7 +566,6 @@ def render(inputs: dict, out_dir: Path, template_path: Path | None = None) -> Pa
         "valuation_block":      _valuation_block(subject, v),
         "subject_narrative":    subject.get("narrative") or "",
 
-        # page 3 — market context
         "summary_headline":     ms["headline"],
         "summary_paragraphs":   _summary_paragraphs(ms["paragraphs"]),
         "kpi_avg_asking":       _money(v["avg_asking"]),
@@ -498,15 +578,12 @@ def render(inputs: dict, out_dir: Path, template_path: Path | None = None) -> Pa
         "demand_note":          ms["demand_note"],
         "spark_svg":            _spark_svg(d.get("growth_series", []), d.get("growth_psf_series", [])),
 
-        # page 4 — comparables
         "sold_comps_rows":      _sold_comps_rows(v.get("sold_comps", [])),
         "asking_comps_tiles":   _asking_comps_tiles(v.get("asking_comps", [])),
 
-        # page 5 — agent listings + sources
         "agent_listings_cards": _agent_listings_cards(inputs["agent_listings"], out_dir),
     }
 
-    # Escape only the plain-text slots; HTML fragments pass through untouched.
     text_slots = {
         "address", "address_short", "postcode", "generated",
         "brand_name", "brand_tagline",
@@ -553,11 +630,6 @@ _PAGE_OBJ_RE = re.compile(rb"/Type\s*/Page(?![sA-Za-z])")
 
 
 def _count_pages(pdf_path: Path) -> int:
-    """pdfinfo first (handles /ObjStm-compressed page-object streams), with a
-    raw /Type /Page byte scan as fallback. The fallback is correct for current
-    Chrome --print-to-pdf output but would undercount if Chrome ever switches
-    to compressed page-object streams — hence pdfinfo first when present.
-    """
     pdfinfo = shutil.which("pdfinfo")
     if pdfinfo:
         result = subprocess.run(
@@ -580,20 +652,113 @@ def assert_page_count(pdf_path: Path, expected: int) -> int:
     return n
 
 
-def _abort(cause: str, hint: str, *, address: str, postcode: str, t0: float, out_dir: Path | None) -> None:
-    """Emit the abort log line, scrub any partial output, exit non-zero."""
+# The 12 PropertyData fan-out tools the preval skill is contracted to call.
+# Each tool the MCP server runs emits a `[property-data] tool=<name> ...` line
+# (see propertydata-api.ts:92). The watchdog asserts every one of these names
+# appears in the log within the 60s budget after `[preval] start`; a missing
+# line means the fan-out silently dropped a call and the agent was about to
+# render against an incomplete payload.
+EXPECTED_PROPERTY_DATA_TOOLS = (
+    "property-data-prices",
+    "property-data-prices-per-sqf",
+    "property-data-sold-prices",
+    "property-data-sold-prices-per-sqf",
+    "property-data-growth",
+    "property-data-growth-psf",
+    "property-data-demand",
+    "property-data-demand-rent",
+    "property-data-property-types",
+    "property-data-crime",
+    "property-data-flood-risk",
+    "property-data-council-tax",
+)
+
+
+def _missing_property_data_tools(log_text: str) -> list[str]:
+    """Return EXPECTED_PROPERTY_DATA_TOOLS that have no `[property-data] tool=<name>` line in log_text."""
+    return [
+        name for name in EXPECTED_PROPERTY_DATA_TOOLS
+        if f"[property-data] tool={name} " not in log_text
+        and not log_text.endswith(f"[property-data] tool={name}")
+        and f"[property-data] tool={name}\n" not in log_text
+    ]
+
+
+def _assert_observability_logs(log_path: Path, *, deadline_s: float = 60.0,
+                               poll_s: float = 2.0, _now=time.monotonic,
+                               _sleep=time.sleep) -> None:
+    """Poll the log until every PropertyData fan-out tool emitted its line.
+
+    Aborts with cause `observability-missing tool=<name>` once deadline_s
+    elapses if any expected name is still missing. `_now` and `_sleep` are
+    injectable for tests so the 60s budget can be exercised without
+    wall-clock waits.
+    """
+    deadline = _now() + deadline_s
+    while True:
+        try:
+            text = log_path.read_text()
+        except OSError:
+            text = ""
+        missing = _missing_property_data_tools(text)
+        if not missing:
+            return
+        if _now() >= deadline:
+            raise PrevalAbort(
+                f"observability-missing tool={missing[0]}",
+                f"PropertyData tool {missing[0]} did not emit "
+                f"`[property-data] tool={missing[0]} ...` within {int(deadline_s)}s "
+                "of [preval] start. The fan-out silently dropped one or more calls; "
+                "re-invoke and confirm every PropertyData tool returned before render. "
+                f"Other missing tool(s): {missing[1:] or 'none'}.",
+            )
+        _sleep(poll_s)
+
+
+def _pick_log_path(out_dir: Path) -> Path:
+    """~/.maxy/logs/server.log if writable, else <out_dir>/preval.log.
+
+    Aborts with `log-destination-unavailable` if neither is writable —
+    silent runs are a contract violation.
+    """
+    primary = Path("~/.maxy/logs/server.log").expanduser()
+    for candidate in (primary, out_dir / "preval.log"):
+        try:
+            candidate.parent.mkdir(parents=True, exist_ok=True)
+            with candidate.open("a"):
+                pass
+            return candidate
+        except OSError:
+            continue
+    raise PrevalAbort(
+        "log-destination-unavailable",
+        "Neither ~/.maxy/logs/server.log nor <out_dir>/preval.log is writable. "
+        "Fix filesystem permissions before re-running.",
+    )
+
+
+def _log_line(log_path: Path | None, line: str) -> None:
+    if log_path is not None:
+        try:
+            with log_path.open("a") as f:
+                f.write(line + "\n")
+        except OSError:
+            pass
+    print(line, file=sys.stderr)
+
+
+def _abort(cause: str, hint: str, *, address: str, postcode: str, t0: float,
+           out_dir: Path | None, log_path: Path | None) -> None:
     ms = int((time.monotonic() - t0) * 1000)
-    print(
+    _log_line(
+        log_path,
         f'[preval] aborted reason={cause} address="{address}" postcode={postcode} ms={ms}',
-        file=sys.stderr,
     )
     print(hint, file=sys.stderr)
     if out_dir is not None:
-        for name in ("index.html",):
-            p = out_dir / name
-            if p.exists():
-                p.unlink()
-        # Any PDF whose stem matches filename_stem would be a partial — caller passes the stem.
+        p = out_dir / "index.html"
+        if p.exists():
+            p.unlink()
     sys.exit(2)
 
 
@@ -604,24 +769,44 @@ def main():
         sys.exit(2)
     inputs = json.loads(Path(sys.argv[1]).read_text())
     out_dir = Path(inputs["out_dir"]).expanduser()
+    out_dir.mkdir(parents=True, exist_ok=True)
     base = inputs["filename_stem"]
     address = inputs.get("address", "")
     postcode = inputs.get("postcode", "")
+
+    try:
+        log_path = _pick_log_path(out_dir)
+    except PrevalAbort as e:
+        _abort(e.cause, e.hint, address=address, postcode=postcode, t0=t0,
+               out_dir=out_dir, log_path=None)
+
+    _log_line(log_path, f'[preval] start address="{address}" postcode={postcode}')
+
+    try:
+        _assert_observability_logs(log_path)
+    except PrevalAbort as e:
+        _abort(e.cause, e.hint, address=address, postcode=postcode, t0=t0,
+               out_dir=out_dir, log_path=log_path)
+
     try:
         render(inputs, out_dir)
         pdf = render_pdf(out_dir, f"{base}.pdf")
         pages = assert_page_count(pdf, 5)
     except PrevalAbort as e:
-        # Scrub partial PDF too, if rendered before page-count failure.
         pdf_path = out_dir / f"{base}.pdf"
         if pdf_path.exists():
             pdf_path.unlink()
-        _abort(e.cause, e.hint, address=address, postcode=postcode, t0=t0, out_dir=out_dir)
+        _abort(e.cause, e.hint, address=address, postcode=postcode, t0=t0,
+               out_dir=out_dir, log_path=log_path)
     except RuntimeError as e:
         pdf_path = out_dir / f"{base}.pdf"
         if pdf_path.exists():
             pdf_path.unlink()
-        _abort("render-error", str(e), address=address, postcode=postcode, t0=t0, out_dir=out_dir)
+        _abort("render-error", str(e), address=address, postcode=postcode, t0=t0,
+               out_dir=out_dir, log_path=log_path)
+
+    ms = int((time.monotonic() - t0) * 1000)
+    _log_line(log_path, f"[preval] done pdf={pdf} pages={pages} ms={ms}")
     print(f"HTML  → {out_dir/'index.html'}")
     print(f"PDF   → {pdf} ({pages} pages)")
 

package/payload/platform/plugins/preval/skills/property-preval/references/template-inputs.schema.json

@@ -1,12 +1,12 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "title": "property-preval inputs",
-  "description": "Single-source contract for render.py. Mirrors the 12 property-data MCP responses + 1 EPC MCP response for one full UK address, plus operator-supplied brand, subject, market_summary, and agent_listings.",
+  "description": "Single-source contract for render.py. Mirrors the 12 property-data MCP responses for one full UK address, plus operator-supplied brand, subject (including the three EPC certificate fields pasted before invocation), market_summary, and agent_listings.",
   "type": "object",
   "required": [
     "out_dir", "filename_stem", "address", "postcode", "generated",
     "brand", "subject", "valuation", "area", "demand_trend",
-    "market_summary", "agent_listings"
+    "market_summary", "agent_listings", "agent_overrides"
   ],
   "properties": {
     "out_dir":       { "type": "string", "description": "Absolute path to the output directory (created if missing)." },
@@ -34,19 +34,17 @@
 
     "subject": {
       "type": "object",
-      "required": ["cover_hero", "sqft", "sqft_m2"],
+      "required": ["cover_hero", "total_floor_area_m2", "current_energy_rating", "lodgement_date"],
       "properties": {
-        "cover_hero":     { "type": "string", "description": "Filesystem path or URL to a photo of the subject property — required for the cover. Renderer asserts the file exists, is ≥ 1200×800, and is not symlinked to another property's folder." },
-        "beds":           { "type": ["integer", "null"] },
-        "type":           { "type": ["string", "null"], "description": "e.g. 'Semi-detached', 'Terraced', 'Flat'." },
-        "tenure":         { "type": ["string", "null"], "description": "e.g. 'Freehold', 'Leasehold'." },
-        "condition":      { "type": ["string", "null"], "description": "'well' | 'average' | 'needs work'." },
-        "sqft":           { "type": "integer", "description": "Total internal area in square feet. Required. Pulled from EPC (m² × 10.7639, rounded) when available; operator paste-in is the only override. Null aborts the run." },
-        "sqft_m2":        { "type": "number", "description": "Total internal area in square metres from the EPC register. Required alongside sqft." },
-        "epc_current":    { "type": ["string", "null"], "description": "Current energy rating, e.g. 'C'." },
-        "epc_potential":  { "type": ["string", "null"], "description": "Potential energy rating, e.g. 'B'." },
-        "epc_lodgement":  { "type": ["string", "null"], "description": "ISO date of the EPC lodgement." },
-        "narrative":      { "type": ["string", "null"], "description": "One short paragraph the operator writes about the subject — shown under the valuation panel." },
+        "cover_hero":             { "type": "string", "description": "Filesystem path or URL to a photo of the subject property — required for the cover. Renderer asserts the file exists, is ≥ 1200×800, and is not symlinked to another property's folder." },
+        "beds":                   { "type": ["integer", "null"] },
+        "type":                   { "type": ["string", "null"], "description": "e.g. 'Semi-detached', 'Terraced', 'Flat'." },
+        "tenure":                 { "type": ["string", "null"], "description": "e.g. 'Freehold', 'Leasehold'." },
+        "condition":              { "type": ["string", "null"], "description": "'well' | 'average' | 'needs work'." },
+        "total_floor_area_m2":    { "type": "number", "description": "Total internal area in square metres, copied verbatim from the EPC certificate. Operator pastes this into inputs.json before invocation. Null aborts with epc-certificate-not-supplied." },
+        "current_energy_rating":  { "type": "string", "description": "Current energy rating from the EPC certificate, e.g. 'C'. Operator paste-in. Null aborts with epc-certificate-not-supplied." },
+        "lodgement_date":         { "type": "string", "description": "ISO date of the EPC certificate's lodgement, e.g. '2018-04-21'. Operator paste-in. Null aborts with epc-certificate-not-supplied." },
+        "narrative":              { "type": ["string", "null"], "description": "One short paragraph the operator writes about the subject — shown under the valuation panel." },
         "adjustments": {
           "type": "array",
           "description": "Operator-curated esoteric factors that shift the headline range. Deltas sum linearly into the final factor (1 + Σ delta_pct/100).",
@@ -155,13 +153,14 @@
 
     "market_summary": {
       "type": "object",
-      "required": ["headline", "paragraphs", "demand_gauge_position", "price_growth_note", "demand_note"],
+      "required": ["headline", "paragraphs", "demand_gauge_position", "price_growth_note", "demand_note", "origin"],
       "properties": {
         "headline":              { "type": "string", "description": "One-line display-italic h2 for the market context page." },
         "paragraphs":            { "type": "array", "minItems": 2, "items": { "type": "string" }, "description": "2–3 short paragraphs. First gets a drop cap. Fewer than 2 aborts the run." },
         "demand_gauge_position": { "type": "string", "description": "Percentage string for the gauge marker position, e.g. '62%'." },
         "price_growth_note":     { "type": "string" },
-        "demand_note":           { "type": "string" }
+        "demand_note":           { "type": "string" },
+        "origin":                { "type": "string", "enum": ["operator", "operator-edited-llm-stub"], "description": "Provenance of the paragraphs. 'agent-invented' is never permitted — the gate aborts with `market-summary-invented`." }
       }
     },
 
@@ -172,7 +171,7 @@
       "description": "Agent's own recent listings to feature on the closing page. Operator paste-in (not the PropertyData sample). Empty array aborts the run.",
       "items": {
         "type": "object",
-        "required": ["address", "price", "status", "slug"],
+        "required": ["address", "price", "status", "slug", "origin"],
         "properties": {
           "url":     { "type": ["string", "null"], "description": "Source URL — listing card becomes an <a> when present." },
           "address": { "type": "string" },
@@ -180,10 +179,21 @@
           "beds":    { "type": ["integer", "null"] },
           "type":    { "type": ["string", "null"] },
           "image":   { "type": ["string", "null"], "description": "Path or URL to a tile photo for the card." },
-          "status":  { "type": "string", "description": "'Sold' | 'Under offer' | 'For sale'." },
-          "slug":    { "type": "string", "description": "Used to name the copied image file under img/." }
+          "status":  { "type": "string", "enum": ["Sold", "Under offer", "For sale"], "description": "Operator picks; no default. The gate aborts if status was set when the source property.json had status:null without agent_overrides.listings_status_curated." },
+          "slug":    { "type": "string", "description": "Used to name the copied image file under img/." },
+          "origin":  { "type": "string", "description": "'operator' when the operator typed the row by hand, or the filesystem path of the source property.json the row was copied from." }
         }
       }
+    },
+
+    "agent_overrides": {
+      "type": "object",
+      "description": "Explicit operator confirmations that authorise bypass of adherence gates. Each override is a named boolean that lands next to the disputed value in inputs.json — auditable post-hoc.",
+      "required": ["brand_selected_by_operator", "listings_status_curated"],
+      "properties": {
+        "brand_selected_by_operator":   { "type": "boolean", "description": "True only when the operator told the agent which estate agent is pitching. Inferring brand from on-disk DESIGN.md files is invention." },
+        "listings_status_curated":      { "type": "boolean", "description": "True only when the operator explicitly signed off on each agent_listings[].status value." }
+      }
     }
   }
 }

package/payload/platform/plugins/property-data/PLUGIN.md

@@ -4,48 +4,70 @@ description: "PropertyData UK market analytics — postcode-keyed valuation, ask
 tools:
   - name: property-data-key-register
     publicAllowlist: false
+    adminAllowlist: false
   - name: property-data-key-deregister
     publicAllowlist: false
+    adminAllowlist: false
   - name: property-data-key-list
     publicAllowlist: false
+    adminAllowlist: false
   - name: property-data-valuation-sale
     publicAllowlist: false
+    adminAllowlist: false
   - name: property-data-valuation-rent
     publicAllowlist: false
+    adminAllowlist: false
   - name: property-data-prices
     publicAllowlist: false
+    adminAllowlist: false
   - name: property-data-prices-rent
     publicAllowlist: false
+    adminAllowlist: false
   - name: property-data-sold-prices
     publicAllowlist: false
+    adminAllowlist: false
   - name: property-data-demand
     publicAllowlist: false
+    adminAllowlist: false
   - name: property-data-yields
     publicAllowlist: false
+    adminAllowlist: false
   - name: property-data-growth
     publicAllowlist: false
+    adminAllowlist: false
   - name: property-data-national-hpi
     publicAllowlist: false
+    adminAllowlist: false
   - name: property-data-prices-per-sqf
     publicAllowlist: false
+    adminAllowlist: false
   - name: property-data-sold-prices-per-sqf
     publicAllowlist: false
+    adminAllowlist: false
   - name: property-data-crime
     publicAllowlist: false
+    adminAllowlist: false
   - name: property-data-flood-risk
     publicAllowlist: false
+    adminAllowlist: false
   - name: property-data-council-tax
     publicAllowlist: false
+    adminAllowlist: false
   - name: property-data-planning-applications
     publicAllowlist: false
+    adminAllowlist: false
   - name: property-data-address-match-uprn
     publicAllowlist: false
+    adminAllowlist: false
   - name: property-data-growth-psf
     publicAllowlist: false
+    adminAllowlist: false
   - name: property-data-demand-rent
     publicAllowlist: false
+    adminAllowlist: false
   - name: property-data-property-types
     publicAllowlist: false
+    adminAllowlist: false
 skills:
   - skills/property-data/SKILL.md
 always: false