@rubytech/create-maxy-code 0.1.61 → 0.1.63

package/payload/premium-plugins/real-agent/plugins/preval/skills/property-preval/references/render.py

@@ -4,11 +4,16 @@ Substitutes <!-- REPLACE: <slot> --> placeholders in template.html with values
 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. 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
 """
 from __future__ import annotations
-import html, json, re, shutil, subprocess, sys
+import html, json, re, shutil, subprocess, sys, time
 from pathlib import Path
 
 
@@ -214,20 +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.
 
-    Falls back to the 'requires floor area' state when subject.sqft is missing.
+    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.get("sqft")
-    if not sqft:
-        return (
-            '<div class="val-panel"><div class="val-empty">'
-            "Estimate requires floor area.<br>"
-            "<span style=\"font-size:10pt;color:var(--text-muted)\">"
-            f"Benchmark: sold £/sqft = {_money(valuation['sold_psf'])}, "
-            f"asking £/sqft = {_money(valuation['asking_psf'])}. "
-            "Paste subject.sqft to compute the range."
-            "</span></div></div>"
-        )
-
+    sqft = _derived_sqft(subject)
     low_psf  = valuation["sold_psf_low"]
     mid_psf  = valuation["sold_psf"]
     high_psf = valuation["sold_psf_high"]
@@ -276,32 +272,246 @@ 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.get("sqft")
-    m2 = subject.get("sqft_m2")
-    if sqft:
-        sub = f"≈ {m2:.0f} m² · from EPC register" if m2 else "Square feet (operator)"
-        return f"{int(sqft):,}", sub
-    return "—", "No EPC on file"
+    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 ----------------
+
+class PrevalAbort(RuntimeError):
+    """Raised when a load-bearing input is missing or unverifiable.
+
+    .cause is the short slug logged as `reason=<cause>` and shown in the
+    operator's remediation hint.
+    """
+    def __init__(self, cause: str, hint: str):
+        super().__init__(f"{cause}: {hint}")
+        self.cause = cause
+        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)."""
+    p = Path(path_str).expanduser()
+    if not p.exists():
+        raise PrevalAbort(
+            "subject-cover-hero-missing",
+            f"cover_hero path does not exist: {p}",
+        )
+    if p.is_symlink():
+        target = p.resolve()
+        parts = target.parts
+        if "properties" in parts:
+            raise PrevalAbort(
+                "subject-cover-hero-symlinked-foreign",
+                f"cover_hero is a symlink into another property's folder: {target}",
+            )
+    w, h = _image_dimensions(p)
+    if w is None or h is None:
+        raise PrevalAbort(
+            "subject-cover-hero-unreadable",
+            f"cover_hero is not a readable PNG or JPEG: {p}",
+        )
+    if w < min_w or h < min_h:
+        raise PrevalAbort(
+            "subject-cover-hero-too-small",
+            f"cover_hero is {w}×{h}, below the {min_w}×{min_h} minimum: {p}",
+        )
+
+
+def _image_dimensions(p: Path) -> tuple[int | None, int | None]:
+    """Return (width, height) for PNG or JPEG. None on any failure."""
+    try:
+        with p.open("rb") as f:
+            head = f.read(24)
+            if len(head) < 24:
+                return None, None
+            if head[:8] == b"\x89PNG\r\n\x1a\n":
+                w = int.from_bytes(head[16:20], "big")
+                h = int.from_bytes(head[20:24], "big")
+                return w, h
+            if head[:2] == b"\xff\xd8":
+                f.seek(2)
+                while True:
+                    b = f.read(1)
+                    while b and b != b"\xff":
+                        b = f.read(1)
+                    marker = f.read(1)
+                    if not marker:
+                        return None, None
+                    if 0xC0 <= marker[0] <= 0xCF and marker[0] not in (0xC4, 0xC8, 0xCC):
+                        f.read(3)
+                        h = int.from_bytes(f.read(2), "big")
+                        w = int.from_bytes(f.read(2), "big")
+                        return w, h
+                    seg_len = int.from_bytes(f.read(2), "big")
+                    f.seek(seg_len - 2, 1)
+            return None, None
+    except OSError:
+        return None, None
+
+
+def _assert_inputs(inputs: dict) -> None:
+    """Fail loud on any missing or unverifiable load-bearing input.
+
+    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 {}
+
+    # --- 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(
+            "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.",
+        )
+
+    hero = subject.get("cover_hero")
+    if not hero:
+        raise PrevalAbort(
+            "subject-cover-hero-missing",
+            "subject.cover_hero is required for the cover page.",
+        )
+    if not hero.startswith(("http://", "https://", "data:")):
+        _assert_path_image(hero)
+
+    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)]
+    if missing_brand:
+        raise PrevalAbort(
+            "brand-unresolved",
+            f"brand is missing required token(s) {missing_brand} — resolve from the agent's on-disk DESIGN.md before invocation.",
+        )
+
+    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.",
+        )
+
+    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 ----------------
 
 def render(inputs: dict, out_dir: Path, template_path: Path | None = None) -> Path:
+    _assert_inputs(inputs)
+
     template_path = template_path or (Path(__file__).parent / "template.html")
     tmpl = template_path.read_text()
 
@@ -326,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"],
@@ -341,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 "—"),
@@ -359,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"]),
@@ -372,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",
@@ -427,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(
@@ -454,16 +652,161 @@ def assert_page_count(pdf_path: Path, expected: int) -> int:
     return n
 
 
+# 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)
+    _log_line(
+        log_path,
+        f'[preval] aborted reason={cause} address="{address}" postcode={postcode} ms={ms}',
+    )
+    print(hint, file=sys.stderr)
+    if out_dir is not None:
+        p = out_dir / "index.html"
+        if p.exists():
+            p.unlink()
+    sys.exit(2)
+
+
 def main():
+    t0 = time.monotonic()
     if len(sys.argv) < 2:
         print("Usage: render.py <inputs.json>", file=sys.stderr)
         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"]
-    render(inputs, out_dir)
-    pdf = render_pdf(out_dir, f"{base}.pdf")
-    pages = assert_page_count(pdf, 5)
+    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:
+        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, 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, 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/premium-plugins/real-agent/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"],
+      "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." },
-        "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", "null"], "description": "Total internal area in square feet. Pulled from EPC (m² × 10.7639, rounded) when available; operator paste-in otherwise. If null, valuation panel switches to 'requires floor area' mode." },
-        "sqft_m2":        { "type": ["number", "null"], "description": "Total internal area in square metres from the EPC register." },
-        "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,23 +153,25 @@
 
     "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", "items": { "type": "string" }, "description": "2–3 short paragraphs. First gets a drop cap." },
+        "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`." }
       }
     },
 
     "agent_listings": {
       "type": "array",
+      "minItems": 1,
       "maxItems": 6,
-      "description": "Agent's own recent listings to feature on the closing page. Operator paste-in (not the PropertyData sample).",
+      "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" },
@@ -179,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/premium-plugins/real-agent/plugins/preval/skills/property-preval/references/template.html

@@ -105,7 +105,6 @@
   .val-final{margin-top:5mm;padding:5mm 6mm;background:var(--teal-900);color:var(--text-on-dark);border-radius:var(--radius-lg);display:flex;justify-content:space-between;align-items:baseline;gap:4mm}
   .val-final .lbl{font-family:var(--sans);font-weight:600;font-size:8pt;letter-spacing:2pt;text-transform:uppercase;color:var(--gold-500)}
   .val-final .num{font-family:var(--display);font-style:italic;font-weight:500;font-size:26pt;color:var(--text-on-dark);letter-spacing:-.4pt}
-  .val-empty{padding:8mm;text-align:center;font-family:var(--display);font-style:italic;font-size:14pt;color:var(--text-muted)}
 
   /* --- TABLES --- */
   table.cmp{width:100%;border-collapse:collapse;font-size:10pt;font-family:var(--body)}