@rubytech/create-maxy-code 0.1.62 → 0.1.64

package/payload/premium-plugins/real-agent/plugins/preval/skills/property-preval/SKILL.md

@@ -1,21 +1,38 @@
 ---
 name: property-preval
-description: Use when an operator wants a pre-valuation pack to pitch for a UK property listing — a 5-page A4 PDF that combines a market-data report for the postcode with the subject property's own valuation range, full-width sold + asking comparables, and the agent's recent successes as the sales close. Triggers include "preval <address>", "pre-valuation for <address>", "valuation pitch for <address>", "what's <address> worth and pitch us to list it", "pre-appraisal pack for <address>".
+description: Use when an operator wants a pre-valuation pack to pitch for a UK property listing — a 7-page A4 PDF that combines subject facts, postcode market context, market depth, vendor-side "what gets the best price" prep tips, full-width sold + asking comparables, and the agent's recent successes as the sales close. Available in two style variants (premium = editorial Cormorant/Lora/Inter lock; on-brand = follows the agent's DESIGN.md fonts end-to-end). Triggers include "preval <address>", "pre-valuation for <address>", "valuation pitch for <address>", "what's <address> worth and pitch us to list it", "pre-appraisal pack for <address>".
 ---
 
 # Property Preval
 
-A 5-page A4 PDF that pitches the agent for the listing: cover (full-bleed subject hero), subject valuation (sqft × £/sqft band with operator adjustments), market context, full-width comparables (sold + asking stacked), and the agent's recent successes + disclaimer. **Preval is a sales pitch, not just a data sheet** — every page either tells the vendor what the property is worth or what the agent has recently delivered nearby.
+A 7-page A4 PDF that pitches the agent for the listing: cover (full-bleed subject hero + agent byline), subject facts, market context, market depth, vendor-side prep tips ("What gets the best price"), full-width comparables, and the agent's recent successes + disclaimer. **Preval is the data-and-comparables half of the pitch — the human agent values the property in person.** The pack never quotes a numeric estimate or range; that's the agent's job, supported by the comparables on page 6.
 
-## Typography is fixed; only colours and logos come from the agent
+## Style variants — premium (default) or on-brand
 
-Same typographic lock as `property-market-report`:
+The pack renders in one of two variants, selected via the top-level `variant` field on `inputs.json`. The two variants share the same content and layout — only typography differs.
+
+### `variant: "premium"` (default — editorial folio)
+
+Typography lock — never substituted:
 
 - **Display** — Cormorant Garamond (italic for headlines, KPI values, prices, addresses)
 - **Body** — Lora
 - **Sans / labels** — Inter (eyebrows, KPI labels, chips, footer meta)
 
-Never substitute the agent's body or display fonts even if their `DESIGN.md` specifies different families. The pack reads as an editorial / luxury document across every brand. The agent's identity comes through the **palette and logo only**.
+The pack reads as an editorial / luxury document across every brand. The agent's identity comes through the **palette and logo only**. The agent's `DESIGN.md` font tokens are ignored.
+
+### `variant: "on-brand"` (follows the agent's DESIGN.md end-to-end)
+
+Renderer reads `brand.font_display` and `brand.font_body` from `inputs.json` (sourced from the agent's `DESIGN.md` font tokens) and overrides the `--display` / `--body` / `--sans` CSS variables. Headlines, body copy, eyebrows and labels all switch to the agent's identity. Colour tokens + logo apply as in premium.
+
+Schema requires `brand.font_display` to be set for `on-brand` to engage — a missing display font silently falls back to the premium lock (no broken render). `brand.font_body` defaults to `brand.font_display` if not supplied.
+
+### Decision rule (mirrors `property-brochure`)
+
+1. Operator said "premium" / "super-premium" / "editorial" → premium (regardless of DESIGN.md).
+2. Operator said "on-brand" / "branded" / "follow our DESIGN.md" → on-brand.
+3. Operator silent + `DESIGN.md` provides both font tokens → on-brand (default for branded shops).
+4. Otherwise → premium.
 
 ## Inputs (never invented)
 
@@ -25,10 +42,15 @@ Never substitute the agent's body or display fonts even if their `DESIGN.md` spe
   - `cover_hero` (filesystem path or URL to a photo of the subject — required for the cover).
   - Optional `beds`, `type`, `tenure`, `condition` (well / average / needs work).
   - `adjustments[]` — operator-curated array of `{label, delta_pct}` covering esoteric factors that shift the headline range (e.g. `{"label":"South-facing garden","delta_pct":3}`, `{"label":"Needs full reno","delta_pct":-8}`). Deltas sum linearly into the final range.
-  - `narrative` — one short paragraph the operator writes about the property.
-  - **Floor area is auto-pulled from the EPC register** via `real-agent-epc` (`epc-lookup-by-address`) and surfaced as `sqft_m2` + derived `sqft`. Both are required. If EPC has no record (pre-2008 property never sold or let; Scotland/NI; unmatched), the operator pastes `subject.sqft` directly **before invocation** as a deliberate override. There is no mid-run paste prompt and no benchmark-only render — a null `sqft` aborts the run with `reason=subject-sqft-missing`.
+  - **EPC certificate fields are pasted by the operator before invocation.** The three required fields are `subject.total_floor_area_m2`, `subject.current_energy_rating`, and `subject.lodgement_date` — copied verbatim from the EPC certificate. The renderer derives `sqft` from `total_floor_area_m2 × 10.7639`. There is no mid-run paste prompt and no benchmark-only render — a null in any of the three aborts the run with `reason=epc-certificate-not-supplied`.
 - **`agent_listings`** — the agent's recent sold / under-offer / live listings to feature on the closing page. Up to 6 entries of `{url, address, price, beds, type, image, status, slug}` where `status ∈ {"Sold","Under offer","For sale"}`. Operator picks the comps that make the strongest pitch; this is *not* the PropertyData sample.
-- **`market_summary`** — `headline` (one display-italic line), `paragraphs[]` (2–3 short paragraphs), `demand_gauge_position` (percentage string like `"62%"`), `price_growth_note`, `demand_note`. The operator drafts or accepts an LLM stub.
+
+## Composed by the agent from the fan-out (never operator-supplied)
+
+Two prose fields are written by the agent from the 12-call PropertyData fan-out plus the EPC and council-tax records — the operator is never prompted for them.
+
+- **`subject.narrative`** — one short paragraph (1–3 sentences) under the valuation panel. Composed from: EPC sqft + rating, `lodgement_date` vs today (age), subject council-tax band (from the per-property `council-tax.properties[]` entry that matches the subject's house number), street context (count of dwellings on the road from the same response), plus the operator's `subject.adjustments[]` labels. Pure facts only — never speculate about orientation, decor, or interior condition that the data doesn't carry.
+- **`market_summary`** — `headline` (one display-italic line), `paragraphs[]` (2–3 short paragraphs), `demand_gauge_position` (percentage string like `"62%"`), `price_growth_note`, `demand_note`. Every value composed from the 12-call fan-out output. Mapping: `headline` summarises the postcode in one line (e.g. demand rating + scarcity + £/sqft direction); paragraph 1 covers £/sqft band (sold vs asking) + Land Registry sample window; paragraph 2 covers demand (for-sale count, sales/mo, MoI, DoM, turnover) + property-type mix; paragraph 3 covers growth (£ + £/sqft YoY) + rental pillar. `demand_gauge_position` maps the demand rating to a percentage: Buyer's market ≈ 20–30%, Balanced market ≈ 45–55%, Seller's market ≈ 75–85%, tuned within band by MoI/DoM.
 
 ## Tools the skill calls
 
@@ -48,57 +70,56 @@ Parallel fan-out keyed on the derived postcode + the subject address:
 11. `property-data-flood-risk` — area flood risk (full postcode only).
 12. `property-data-council-tax` — band D + per-property bands (full postcode only).
 
-**EPC (1 call — free, rate-limited):**
-
-13. `epc-lookup-by-address(address, postcode)` — subject floor area + energy ratings + lodgement date.
+EPC certificate fields are operator paste-in — see `subject.total_floor_area_m2`, `subject.current_energy_rating`, `subject.lodgement_date` in the Inputs section. There is no EPC MCP fan-out.
 
 `address-match-uprn` and `planning-applications` are deliberately omitted (CRM hygiene and dev-precedent reports respectively).
 
 ## Output
 
-Directory under `~/Documents/Maxy/preval/<postcode-compact>-<YYYY-MM-DD>/` containing:
+Directory under `~/estate-agents/<brand-slug>/preval/<address-slug>/` (e.g. `~/estate-agents/muvin/preval/11-phoenix-drive-cm23-2uj/`) containing:
 
 - `index.html` — single self-contained file.
 - `img/` — copied logos and the subject hero image.
-- `<slug>-<date>.pdf` — exactly **5** A4 pages. Renderer asserts via `pdfinfo` and raises if ≠ 5.
+- `<slug>-<date>.pdf` — exactly **7** A4 pages. Renderer asserts via `pdfinfo` and raises if ≠ 7.
+- `property-data.md` — markdown dump of the 12 raw PropertyData fan-out responses for transparency / vendor audit (operator may share or strip before sending).
+- `inputs.json` + `preval.log` — the assembled input shape + the `[preval]` start/done/aborted audit lines.
 
-Return the PDF path to the operator.
+Output is agent-centric so each brand owns its own preval history alongside its `properties/`, `reports/` and `DESIGN.md`. Return the PDF path to the operator.
 
 ## Pages
 
-1. **Cover** — full-bleed `subject.cover_hero` with vertical gradient scrim; light logo top-left; eyebrow "`<brand.name>` · Pre-valuation"; address in display-italic; postcode chip; four-up meta strip (Report · Address · Postcode · Generated). Lifted from property-market-report's cover contract.
-2. **Subject valuation** — KPI strip (sqft, beds, EPC rating, type). Centre panel: headline range = `sqft × sold_psf_low–high` (Land Registry 70pc band) with `sqft × asking_psf` shown as a cross-check. Operator `adjustments[]` displayed as a stacked list (label · delta% · running £). Final range pill at the foot. One paragraph of `subject.narrative` under the panel. `sqft` is required — a null value aborts the run, never renders a benchmark-only panel.
-3. **Market context** — KPI cube (avg asking, avg sold, £/sqft, YoY); pill + gauge for demand; 7y growth sparkline (£ solid + £/sqft dashed); summary paragraphs. Same patterns as property-market-report's page 2.
-4. **Comparables (full-width, stacked)** — Nearest sold table (top 6) full-width across the page; Live asking tile grid (top 4) full-width below. Vertically stacked, never side-by-side — corrects the cramped two-column layout in the v1 preval where the asking tiles got pushed to ~40mm columns of italic addresses.
-5. **Recently with `<brand.name>` + sources** — agent's own listings as a clickable tile grid (`<a>` per card, status badge: Sold / Under offer / For sale), then the sources / methodology / accuracy / investment block. Closes with `Real Agent · Generated <date> · <postcode>` in the footer.
+1. **Cover** — full-bleed `subject.cover_hero` with vertical gradient scrim; light logo top-left; eyebrow "`<brand.name>` · Pre-valuation"; address in display-italic; postcode chip; four-up meta strip (Prepared by · Address · Postcode · Generated). When `brand.agent_name` is set, "Prepared by" displays that name (ties the cover photo to the individual agent pitching).
+2. **About the property** — KPI strip (sqft, beds, EPC rating, type, tenure). Agent-composed `subject.narrative` under the KPIs (drawn from EPC + council-tax records — see "Composed by the agent from the fan-out"). Optional "Notable features" bullet list rendered from `subject.adjustments[].label` (label-only — `delta_pct` is held in the schema for backward compat but no longer rendered). **No estimate, no range, no adjustments-with-running-£**. `sqft` is required — a null value aborts the run, never renders a benchmark-only panel.
+3. **Market context** — Market-summary headline + 2–3 paragraphs (dropcap on first); KPI cube (avg asking, avg sold, £/sqft); two-col panels (price growth + demand gauge). The 7-year chart used to live here; it now has its own page (page 4) to give it space.
+4. **Market depth** — Full-width 7-year price-trend chart (£ headline solid + £/sqft dashed gold, ≈ 48mm tall). Below: two-col panels — output-area stock mix (`demand_trend.type_dist` bars) on the left, rental pillar on the right (`demand_trend.rating` pill + 3-up KPIs for for-rent count, DoM, monthly take-up).
+5. **What gets the best price** — Vendor-facing prep advice condensed from `real-agent/listings/home-preparation/staging-guide.md`. Two-col panel: "Five high-impact moves" (declutter / deep-clean / open the light / fix the small things / define each room) on the left; "Common mistakes" (air fresheners / personal items / cold house / overgrown garden / wardrobes) on the right. Closes with a line attributing the room-by-room walkthrough to the agent ("`<agent_name>` can walk you through this room-by-room ahead of photo day."). Content is hard-coded into the template — not per-pack-editable; for per-property customisation operators should swap to the brochure flow.
+6. **Comparables (full-width, stacked)** — Nearest sold table (top 6, columns Date · Address · Type · Beds · Price) full-width across the page; Live asking tile grid (top 4) full-width below. Vertically stacked, never side-by-side — corrects the cramped two-column layout in the v1 preval where the asking tiles got pushed to ~40mm columns of italic addresses.
+7. **Recently with `<brand.name>` + sources** — agent's own listings as a clickable tile grid (`<a>` per card, status badge: Sold / Under offer / For sale), then the sources / methodology / accuracy / investment block. Closes with `<brand.name> · Generated <date> · <postcode>` in the footer.
 
 ## How to execute
 
 1. Match the postcode out of the address (`/[A-Z]{1,2}[0-9][A-Z0-9]?\s?[0-9][A-Z]{2}/i`). Stop if no match.
-2. Run the 13 fan-out tools (12 PropertyData + 1 EPC) in parallel. Every failure is fail-loud — no mid-run paste prompts, no benchmark-only render, no degraded pack on disk:
+2. Run the 12 PropertyData fan-out tools in parallel. Every failure is fail-loud — no mid-run paste prompts, no benchmark-only render, no degraded pack on disk:
    - **PropertyData `key-not-registered`** → abort `reason=property-data-key-not-registered` with the `property-data-key-register` remediation hint.
    - **PropertyData `http-429`** → back off and retry the single throttled tool **once**. A second `http-429` aborts `reason=property-data-rate-limited`.
    - **PropertyData `http-5xx` / network failure** → abort `reason=property-data-unavailable`.
-   - **EPC failure of any kind** — `key-not-registered`, `http-404 (no record on file)`, `http-429`, `http-5xx`, network failure, or MCP not configured on the account — aborts the run. The operator's options before re-running are (a) run Task 155 to deploy / register the EPC MCP, or (b) paste `subject.sqft` (plus `subject.sqft_m2`) into the inputs as a deliberate operator override. There is no in-band prompt and no benchmark-only mode.
-3. Compute valuation range:
-   - `sold_psf_low` = `sold-prices-per-sqf` `70pc_range[0]`
-   - `sold_psf_high` = `sold-prices-per-sqf` `70pc_range[1]`
-   - `low = sqft × sold_psf_low`, `mid = sqft × sold_psf`, `high = sqft × sold_psf_high`
-   - Apply `adjustments` linearly: `factor = 1 + Σ delta_pct / 100`. Final range = `[low × factor, high × factor]`, midpoint = `mid × factor`.
-4. Assemble the `inputs.json` shape per `references/template-inputs.schema.json`.
-5. `python3 references/render.py inputs.json`. Renderer fills the template, copies logos + hero into `img/`, drives Chrome `--print-to-pdf`, asserts page count == 5.
-6. Return the PDF path.
+   - **Watchdog: any of the 12 PropertyData log lines missing** within 60 s of `[preval] start` → `render.py` aborts `reason=observability-missing tool=<name>` naming the silent tool. A silent tool drop must never proceed to render.
+3. Derive `sqft` from `round(subject.total_floor_area_m2 × 10.7639)` for the page-2 KPI strip. The pack does not compute a £-valuation; the £/sqft band lives on page 3 (market context) and the comparables on page 4 — the human agent values from those in person.
+4. Compose `subject.narrative` and `market_summary` from the fan-out output per the rules in "Composed by the agent from the fan-out". No operator prompt for either.
+5. Assemble the `inputs.json` shape per `references/template-inputs.schema.json`.
+6. `python3 references/render.py inputs.json`. Renderer fills the template, copies logos + hero into `img/`, drives Chrome `--print-to-pdf`, asserts page count == 7.
+7. Return the PDF path.
 
-## Adjustments — linear vs compound
+## Adjustments — label-only
 
-Deltas sum linearly (`-8 + 3 = -5%`, applied as `× 0.95`). Compound interpretation (`× 0.92 × 1.03`) would give a slightly different number (-5.24%) but the operator presents the figures verbally as a sum, so the displayed maths must match the verbal claim. If a future operator wants compound adjustments, this is a deliberate skill-level rewrite, not a config switch.
+`subject.adjustments[]` survives in the schema as `{label, delta_pct}` but the renderer uses only the `label` field — rendered as a "Notable features" bullet list on page 2. `delta_pct` is held for backward compat (it used to drive a numeric range that this skill no longer publishes). The human agent factors notable features into their valuation conversation; the pack just surfaces them as facts.
 
 ## Observability
 
 - `[preval] start address="<addr>" postcode=<pc>` at run start.
 - `[preval] done pdf=<path> pages=<n> ms=<n>` at run end.
 - `[preval] aborted reason=<cause> address="<addr>" postcode=<pc> ms=<n>` on any abort (one line, then exit 2; no `done`).
-- Each fan-out call emits its own `[property-data] tool=<name>` or `[epc] tool=<name>` line in `server.log` (inherited contracts; no new instrumentation here).
+- Each fan-out call emits its own `[property-data] tool=<name>` line in `server.log` (inherited contract; no new instrumentation here). `render.py`'s observability watchdog tails these lines and aborts with `observability-missing tool=<name>` if any of the 12 expected names is absent 60 s after `[preval] start`.
 
 ## Hard breakpoints
 
@@ -106,26 +127,24 @@ Each row aborts the run with the named cause. No PDF or `index.html` is left on
 
 | Forbidden state | `reason=` cause |
 |---|---|
-| EPC MCP not configured / `key-not-registered` / `http-5xx` / network error | `epc-mcp-unavailable` (operator must run Task 155 or paste `subject.sqft` before invocation) |
-| `subject.sqft` null after EPC lookup | `subject-sqft-missing` |
-| `subject.sqft_m2` null | `subject-sqft-m2-missing` |
+| `subject.total_floor_area_m2` / `current_energy_rating` / `lodgement_date` null or missing | `epc-certificate-not-supplied` (operator pastes the three fields from the EPC certificate before re-invoking) |
 | `subject.cover_hero` missing, unreachable, below 1200×800, or symlinked into another property's folder | `subject-cover-hero-missing` / `subject-cover-hero-unreadable` / `subject-cover-hero-too-small` / `subject-cover-hero-symlinked-foreign` |
 | `brand` not resolved from an on-disk `DESIGN.md` (required token missing) | `brand-unresolved` |
 | `agent_listings` empty | `agent-listings-empty` |
 | `market_summary.paragraphs` < 2 entries | `market-summary-too-thin` |
 | PropertyData any-call `http-429` after 1 retry | `property-data-rate-limited` |
 | PropertyData any-call `key-not-registered` | `property-data-key-not-registered` (operator runs `property-data-key-register`) |
-| EPC lookup returns `http-404` (no record on file) | `epc-no-record` (operator pastes `subject.sqft` as override and re-runs, or accepts that this address can't be preval'd until lodged) |
+| Any of the 12 PropertyData log lines missing 60 s after `[preval] start` | `observability-missing tool=<name>` (the silent tool is named in the abort hint) |
 
 ## Forbidden behaviours
 
 The skill is the contract; if any of these slip through, the pack must not render:
 
 - Silent fallback selection — switching to a benchmark-only / "Estimate requires floor area" panel when an input is missing.
-- Inventing inputs — fabricating `brand`, `subject.cover_hero`, `market_summary.paragraphs`, `agent_listings`, or any field the operator did not supply.
+- Inventing operator-supplied inputs — fabricating `brand`, `subject.cover_hero`, `agent_listings`, the three EPC certificate fields, or `subject.adjustments[]`. `subject.narrative` and `market_summary` are NOT operator-supplied — the agent composes them from the fan-out (see "Composed by the agent from the fan-out").
 - Reusing a hero photo from a different property as a placeholder.
 - Defaulting `agent_listings[].status` to `"For sale"` when the source is null.
-- Mid-run prompts for a paste-in (EPC retries, sqft, etc). Overrides are operator-supplied **before** invocation.
+- Mid-run prompts for a paste-in. The three EPC certificate fields and every other operator-supplied input are pasted into `inputs.json` **before** invocation; there is no retry / paste-and-resume path.
 - Omitting the `[preval]` start / done / aborted log emissions.
 - Leaving partial output (`index.html`, `<stem>.pdf`) on disk after an abort.
 
@@ -135,12 +154,45 @@ The skill is the contract; if any of these slip through, the pack must not rende
 - `start` with no matching `done` or `aborted` within 60s → renderer crashed mid-run. Inspect with `grep -B2 -A20 '\[preval\] start address="<echoed>"' server.log`.
 - `[preval] aborted reason=<cause>` → look up `<cause>` in the **Hard breakpoints** table for the remediation hint.
 
+## Adherence — non-negotiable
+
+These rules override every session-level "skip clarifying questions", "make the reasonable call", or "work without stopping" directive the operator has set. The named breakpoints below are documented contract points, not casual asks — the renderer and the PreToolUse hook both enforce them and a run that violates one aborts with a named cause.
+
+- **Prompt at named breakpoints — no exceptions.** Named breakpoints: EPC certificate fields not supplied, cover_hero not depicting the subject, brand identity (which estate agent is pitching), `agent_listings` empty or carrying invented statuses. The load-bearing inputs themselves (EPC certificate fields, cover_hero, brand tokens) are gated by `render.py`'s `_assert_inputs`; this section layers provenance on top. `subject.narrative` and `market_summary` are not on this list — they are agent-composed from the fan-out, never operator-prompted.
+- **Never invent operator-supplied inputs.** Brand identity, brand tokens, cover hero, agent listings, listing statuses, subject tenure / beds / type / condition, the three EPC certificate fields, and `subject.adjustments[]` — all operator-supplied. Defaulting from "area pattern", a sister property's photo, "the only DESIGN.md I found on disk", or "status:null in the source so I picked For sale" is invention. The presence of a single `~/estate-agents/<slug>/DESIGN.md` on disk does not authorise its selection — only an operator instruction does. If more than one `~/estate-agents/<slug>/` exists and the operator has not named which one is pitching, abort. (`subject.narrative` and `market_summary` are explicitly out of scope here — see "Composed by the agent from the fan-out".)
+- **`agent_overrides` is the only bypass channel.** Every override the operator authorises lands in `inputs.json` as a named boolean (`brand_selected_by_operator`, `listings_status_curated`) so the audit trail sits next to the disputed value. Setting an override without a real operator instruction is a violation of the same contract.
+- **Emit the three `[preval]` log lines — every run.** `[preval] start address="…" postcode=…`, then `[preval] done pdf=… pages=… ms=…` on success or `[preval] aborted reason=<cause> ms=…` on any abort. A run that emits neither `done` nor `aborted` is itself a defect.
+
+### Named abort causes
+
+| Cause | Trigger | Operator remediation |
+|---|---|---|
+| `cover-hero-not-subject` | `subject.cover_hero` resolves to a `*/properties/*/` directory whose slug doesn't contain the subject's primary street token | Supply the subject's own photo |
+| `agent-listings-invented` | An `agent_listings[].status` is set when the source `property.json` (named by `agent_listings[].origin`) carries `status: null`, and `agent_overrides.listings_status_curated` is not `true` | Operator signs off on each listing status, then sets the override |
+| `brand-invented` | `brand.name` is set without `agent_overrides.brand_selected_by_operator: true` | Operator names which estate agent is pitching; set the override |
+| `epc-certificate-not-supplied` | Any of `subject.total_floor_area_m2`, `subject.current_energy_rating`, or `subject.lodgement_date` is null or missing | Operator copies the three fields verbatim from the EPC certificate into `subject` in `inputs.json` before re-invoking |
+| `observability-missing tool=<name>` | One of the 12 expected `[property-data] tool=<name>` log lines did not appear within 60 s of `[preval] start` | Re-invoke and confirm every PropertyData tool returns; if a tool is genuinely down, surface a `property-data-*` cause first |
+| `log-destination-unavailable` | Neither `~/.maxy/logs/server.log` nor `<out_dir>/preval.log` is writable | Fix filesystem permissions before re-running |
+
+## Self-check before declaring done
+
+Answer all seven inline at the end of every run, with line references from `server.log` or `<out_dir>/preval.log` — not paraphrase:
+
+1. `[preval] start` emitted? (cite the log line)
+2. All 12 expected `[property-data] tool=<name>` log lines present, or `[preval] aborted` emitted with a named cause? (cite the lines)
+3. EPC certificate fields (`subject.total_floor_area_m2`, `subject.current_energy_rating`, `subject.lodgement_date`) all populated from the operator paste? (cite the `inputs.json` excerpt)
+4. Every input field traceable to a real source — operator paste (including the EPC certificate), on-disk `DESIGN.md`, MCP response? Anything sourced from "area pattern", a sister property file, or LLM imagination is a defect.
+5. `[preval] done pages=7` emitted? (cite the log line)
+6. PDF page count = 7 asserted? (cite the assertion result)
+7. No operator-supplied fields invented from area pattern, sister-property files, or LLM imagination? List the three most fabrication-prone operator-supplied fields (`brand.name`, `agent_listings[].status`, `subject.cover_hero`) and the source for each in this run. (`subject.narrative` and `market_summary` are agent-composed from the fan-out by design — note them as such with the data fields they're drawn from.)
+8. **Visual verification — open the rendered PDF and confirm each page.** Use the Read tool with `pages: "1-7"` against the PDF and check: (a) no content clipped at the bottom of any page (the absolutely-positioned `.doc-foot` overlays content past ~y=288mm — anything below must be footer only); (b) no remaining `<!-- REPLACE: <slot> -->` strings; (c) no KPI cells displaying "—" for fields that should be populated (especially `subject.beds`); (d) cover meta strip carries "Prepared by · <agent_name>"; (e) when `variant: "on-brand"` is set, page 1's address renders in the brand's display font (not Cormorant) — typeface drift is the variant's visual signature. Log-line success (`pages=7`) is necessary but not sufficient — page count being right does not prove each page rendered cleanly. **Skipping this check is the documented cause of two prior chart-overflow regressions; treat it as mandatory.**
+
 ## Out of scope
 
 - Multi-address batch preval (CSV in → many PDFs out).
 - Loop CRM auto-publish of the PDF onto a contact's record.
 - Pulling `agent_listings` from Loop CRM automatically — operator paste-in for now; CRM wire-up is a separate task.
-- Caching of MCP responses (13 credits per pack is acceptable).
+- Caching of MCP responses (12 credits per pack is acceptable).
 - A separate cover letter / pitch letter — the cover page *is* the pitch.
 - Compound adjustments (linear sum is the contract; see above).
-- Subject sqft from sources other than EPC and the operator paste-in fallback (e.g. Loop CRM floor plans, Rightmove sqft scrape) — separate task if pursued.
+- Subject EPC fields from sources other than the operator paste-in (e.g. Loop CRM floor plans, Rightmove sqft scrape, restored EPC API) — separate task if pursued.

package/payload/premium-plugins/real-agent/plugins/preval/skills/property-preval/references/__tests__/adherence.test.py

@@ -0,0 +1,373 @@
+"""Adherence-gate tests for property-preval (Tasks 157 + 163).
+
+Covers:
+
+  Task 157 provenance causes (agent didn't invent the input):
+    - cover-hero-not-subject     (slug heuristic; complements 156's symlink check)
+    - agent-listings-invented    (status set when source property.json had null)
+    - market-summary-invented    (origin missing or "agent-invented")
+    - brand-invented             (brand.name without operator override)
+    - log-destination-unavailable (observability emit-or-abort)
+
+  Task 163 causes (replaces 156's sqft gates after EPC removal):
+    - epc-certificate-not-supplied  (any of the three operator-paste EPC
+                                     fields missing — render.py + hook)
+    - observability-missing tool=<name>  (one of the 12 expected
+                                          [property-data] tool=<name> log
+                                          lines absent within the budget)
+
+Plus the PreToolUse hook red-team (blocks the same causes before
+inputs.json reaches disk).
+
+Run with:  python3 references/__tests__/adherence.test.py
+"""
+from __future__ import annotations
+import json, os, struct, subprocess, sys, tempfile, unittest, zlib
+from pathlib import Path
+
+HERE = Path(__file__).resolve().parent
+REFERENCES = HERE.parent
+PLUGIN_ROOT = REFERENCES.parent.parent.parent
+HOOK = PLUGIN_ROOT / "hooks" / "preval-prompt-required.sh"
+
+sys.path.insert(0, str(REFERENCES))
+from render import (  # noqa: E402
+    _assert_inputs,
+    _assert_observability_logs,
+    EXPECTED_PROPERTY_DATA_TOOLS,
+    PrevalAbort,
+)
+
+
+def _write_png(path: Path, w: int = 1600, h: int = 1200) -> None:
+    """Minimal valid PNG large enough to clear Task 156's 1200x800 gate."""
+    def chunk(tag: bytes, data: bytes) -> bytes:
+        return struct.pack(">I", len(data)) + tag + data + struct.pack(">I", zlib.crc32(tag + data) & 0xffffffff)
+    sig = b"\x89PNG\r\n\x1a\n"
+    ihdr = struct.pack(">IIBBBBB", w, h, 8, 2, 0, 0, 0)
+    raw = b"".join(b"\x00" + b"\x00\x00\x00" * w for _ in range(h))
+    idat = zlib.compress(raw)
+    path.write_bytes(sig + chunk(b"IHDR", ihdr) + chunk(b"IDAT", idat) + chunk(b"IEND", b""))
+
+
+def _complete_inputs(tmp: Path) -> dict:
+    """An inputs.json that PASSES every 156 + 157 gate."""
+    hero = tmp / "hero.png"
+    _write_png(hero)
+    return {
+        "out_dir": str(tmp),
+        "filename_stem": "subject",
+        "address": "9 Phoenix Drive, Bishop's Stortford, CM23 2UJ",
+        "postcode": "CM23 2UJ",
+        "generated": "19 May 2026",
+        "brand": {
+            "name": "Muvin",
+            "tagline": "Estate Agents",
+            "primary": "#000", "primary_dark": "#000", "accent": "#000",
+            "paper": "#fff", "paper_banded": "#fff", "rule": "#000",
+        },
+        "subject": {
+            "cover_hero": str(hero),
+            "total_floor_area_m2": 93.2,
+            "current_energy_rating": "C",
+            "lodgement_date": "2018-04-21",
+        },
+        "valuation": {
+            "avg_asking": 500000, "asking_psf": 450, "avg_sold": 480000,
+            "sold_psf": 440, "sold_psf_low": 400, "sold_psf_high": 480,
+            "sold_comps": [], "asking_comps": [],
+        },
+        "area": {
+            "crime_rating": "Low", "flood_risk": "Low", "council_tax_band_d": 2000,
+            "population": 1000, "crime_breakdown": [], "council_tax_bands": [],
+            "headline": "",
+        },
+        "demand_trend": {
+            "demand_rating": "High", "dom": 30, "turnover_pct": 5, "for_sale": 10,
+            "growth_series": [], "growth_psf_series": [],
+            "rental": {"demand_rating": "High", "dom": 20, "turnover_pct": 4, "for_rent": 5},
+            "type_dist": [],
+        },
+        "market_summary": {
+            "headline": "Bishop's Stortford is selling.",
+            "paragraphs": ["The market is active.", "Prices held flat YoY."],
+            "demand_gauge_position": "62%",
+            "price_growth_note": "Up 3% YoY.",
+            "demand_note": "High demand.",
+            "origin": "operator",
+        },
+        "agent_listings": [
+            {
+                "address": "1 Some Road, CM23",
+                "price": 600000,
+                "status": "Sold",
+                "slug": "1-some-road",
+                "origin": "operator",
+            }
+        ],
+        "agent_overrides": {
+            "brand_selected_by_operator": True,
+            "listings_status_curated": False,
+        },
+    }
+
+
+class TestAdherenceGate(unittest.TestCase):
+    def setUp(self):
+        self._tmp = tempfile.TemporaryDirectory()
+        self.tmp = Path(self._tmp.name)
+
+    def tearDown(self):
+        self._tmp.cleanup()
+
+    def _assert_aborts(self, inputs: dict, cause: str):
+        with self.assertRaises(PrevalAbort) as ctx:
+            _assert_inputs(inputs)
+        self.assertEqual(ctx.exception.cause, cause)
+        self.assertFalse(any(self.tmp.glob("*.pdf")))
+
+    def test_clean_run_passes(self):
+        _assert_inputs(_complete_inputs(self.tmp))
+
+    def test_cover_hero_not_subject(self):
+        # Plant the hero PNG in a sister property's folder to trigger the
+        # 157 slug heuristic. 156's symlink check passes (real file, not
+        # a symlink); only the 157 cause should fire.
+        sister = self.tmp / "estate-agents" / "muvin" / "properties" / "07-the-old-orchard-rye-street-cm23"
+        sister.mkdir(parents=True)
+        bad_hero = sister / "hero.png"
+        _write_png(bad_hero)
+        inputs = _complete_inputs(self.tmp)
+        inputs["subject"]["cover_hero"] = str(bad_hero)
+        self._assert_aborts(inputs, "cover-hero-not-subject")
+
+    def test_cover_hero_subject_match_passes(self):
+        subject_dir = self.tmp / "estate-agents" / "muvin" / "properties" / "9-phoenix-drive-cm23-2uj"
+        subject_dir.mkdir(parents=True)
+        good_hero = subject_dir / "hero.png"
+        _write_png(good_hero)
+        inputs = _complete_inputs(self.tmp)
+        inputs["subject"]["cover_hero"] = str(good_hero)
+        _assert_inputs(inputs)
+
+    def test_agent_listings_invented_status(self):
+        source = self.tmp / "source.json"
+        source.write_text(json.dumps({"status": None, "address": "1 Some Road"}))
+        inputs = _complete_inputs(self.tmp)
+        inputs["agent_listings"][0]["origin"] = str(source)
+        inputs["agent_overrides"]["listings_status_curated"] = False
+        self._assert_aborts(inputs, "agent-listings-invented")
+
+    def test_agent_listings_curated_override_passes(self):
+        source = self.tmp / "source.json"
+        source.write_text(json.dumps({"status": None, "address": "1 Some Road"}))
+        inputs = _complete_inputs(self.tmp)
+        inputs["agent_listings"][0]["origin"] = str(source)
+        inputs["agent_overrides"]["listings_status_curated"] = True
+        _assert_inputs(inputs)
+
+    def test_market_summary_invented_missing_origin(self):
+        inputs = _complete_inputs(self.tmp)
+        inputs["market_summary"].pop("origin")
+        self._assert_aborts(inputs, "market-summary-invented")
+
+    def test_market_summary_invented_explicit(self):
+        inputs = _complete_inputs(self.tmp)
+        inputs["market_summary"]["origin"] = "agent-invented"
+        self._assert_aborts(inputs, "market-summary-invented")
+
+    def test_brand_invented(self):
+        inputs = _complete_inputs(self.tmp)
+        inputs["agent_overrides"]["brand_selected_by_operator"] = False
+        self._assert_aborts(inputs, "brand-invented")
+
+    def test_epc_certificate_not_supplied_missing_m2(self):
+        inputs = _complete_inputs(self.tmp)
+        del inputs["subject"]["total_floor_area_m2"]
+        self._assert_aborts(inputs, "epc-certificate-not-supplied")
+
+    def test_epc_certificate_not_supplied_missing_rating(self):
+        inputs = _complete_inputs(self.tmp)
+        inputs["subject"]["current_energy_rating"] = None
+        self._assert_aborts(inputs, "epc-certificate-not-supplied")
+
+    def test_epc_certificate_not_supplied_missing_lodgement(self):
+        inputs = _complete_inputs(self.tmp)
+        inputs["subject"]["lodgement_date"] = ""
+        self._assert_aborts(inputs, "epc-certificate-not-supplied")
+
+
+class TestPreToolUseHook(unittest.TestCase):
+    def _run_hook(self, tool_name: str, file_path: str, content_obj: dict) -> tuple[int, str]:
+        payload = json.dumps({
+            "tool_name": tool_name,
+            "tool_input": {"file_path": file_path, "content": json.dumps(content_obj)},
+        })
+        result = subprocess.run(
+            ["bash", str(HOOK)],
+            input=payload,
+            capture_output=True,
+            text=True,
+        )
+        return result.returncode, result.stderr
+
+    def test_hook_blocks_market_summary_invented(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            inputs = _complete_inputs(Path(tmp))
+            inputs["market_summary"]["origin"] = "agent-invented"
+            code, stderr = self._run_hook(
+                "Write",
+                f"{tmp}/preval/CM232UJ-2026-05-19/inputs.json",
+                inputs,
+            )
+            self.assertEqual(code, 2, msg=stderr)
+            self.assertIn("market-summary-invented", stderr)
+
+    def test_hook_blocks_brand_invented(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            inputs = _complete_inputs(Path(tmp))
+            inputs["agent_overrides"]["brand_selected_by_operator"] = False
+            code, stderr = self._run_hook(
+                "Write",
+                f"{tmp}/preval/CM232UJ-2026-05-19/inputs.json",
+                inputs,
+            )
+            self.assertEqual(code, 2, msg=stderr)
+            self.assertIn("brand-invented", stderr)
+
+    def test_hook_passthrough_unrelated_path(self):
+        code, _ = self._run_hook(
+            "Write",
+            "/tmp/some-other-file.json",
+            {"hello": "world"},
+        )
+        self.assertEqual(code, 0)
+
+    def test_hook_passthrough_unrelated_tool(self):
+        code, _ = self._run_hook(
+            "Bash",
+            "/whatever/preval/inputs.json",
+            {},
+        )
+        self.assertEqual(code, 0)
+
+    def test_hook_blocks_epc_certificate_not_supplied(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            inputs = _complete_inputs(Path(tmp))
+            inputs["subject"]["current_energy_rating"] = None
+            code, stderr = self._run_hook(
+                "Write",
+                f"{tmp}/preval/CM232UJ-2026-05-19/inputs.json",
+                inputs,
+            )
+            self.assertEqual(code, 2, msg=stderr)
+            self.assertIn("epc-certificate-not-supplied", stderr)
+            self.assertIn("current_energy_rating", stderr)
+
+
+class TestObservability(unittest.TestCase):
+    def test_log_destination_unavailable_aborts(self):
+        from render import _pick_log_path
+        ro = Path("/dev/null/cannot-write-here")
+        old_home = os.environ.get("HOME")
+        with tempfile.TemporaryDirectory() as tmp:
+            holder = Path(tmp) / "not-a-dir"
+            holder.write_text("")
+            os.environ["HOME"] = str(holder)
+            try:
+                with self.assertRaises(PrevalAbort) as ctx:
+                    _pick_log_path(ro)
+                self.assertEqual(ctx.exception.cause, "log-destination-unavailable")
+            finally:
+                if old_home is not None:
+                    os.environ["HOME"] = old_home
+                else:
+                    del os.environ["HOME"]
+
+
+class TestObservabilityWatchdog(unittest.TestCase):
+    """Task 163 — 12-call PropertyData fan-out watchdog."""
+
+    def setUp(self):
+        self._tmp = tempfile.TemporaryDirectory()
+        self.tmp = Path(self._tmp.name)
+        self.log_path = self.tmp / "preval.log"
+
+    def tearDown(self):
+        self._tmp.cleanup()
+
+    def _write_log(self, present_tools: list[str]) -> None:
+        lines = [
+            f"[property-data] tool={name} account=local postcode=CM232UJ status=ok ms=42"
+            for name in present_tools
+        ]
+        self.log_path.write_text("\n".join(lines) + "\n")
+
+    def test_all_12_present_passes(self):
+        self._write_log(list(EXPECTED_PROPERTY_DATA_TOOLS))
+        _assert_observability_logs(self.log_path, deadline_s=0.0)
+
+    def test_missing_growth_psf_aborts(self):
+        present = [t for t in EXPECTED_PROPERTY_DATA_TOOLS if t != "property-data-growth-psf"]
+        self._write_log(present)
+        with self.assertRaises(PrevalAbort) as ctx:
+            _assert_observability_logs(self.log_path, deadline_s=0.0)
+        self.assertEqual(
+            ctx.exception.cause,
+            "observability-missing tool=property-data-growth-psf",
+        )
+        self.assertIn("property-data-growth-psf", ctx.exception.hint)
+
+    def test_missing_flood_risk_aborts(self):
+        present = [t for t in EXPECTED_PROPERTY_DATA_TOOLS if t != "property-data-flood-risk"]
+        self._write_log(present)
+        with self.assertRaises(PrevalAbort) as ctx:
+            _assert_observability_logs(self.log_path, deadline_s=0.0)
+        self.assertEqual(
+            ctx.exception.cause,
+            "observability-missing tool=property-data-flood-risk",
+        )
+
+    def test_polls_until_late_arriving_line_lands(self):
+        """The watchdog must keep polling within the budget; a late arrival
+        before the deadline is a pass, not an abort. Wall-clock waits are
+        replaced by injected _now/_sleep so the test stays fast."""
+        present = [t for t in EXPECTED_PROPERTY_DATA_TOOLS if t != "property-data-prices"]
+        self._write_log(present)
+        ticks = iter([0.0, 1.0, 2.0])  # never reaches deadline_s=10
+        appended = []
+
+        def fake_sleep(s):
+            appended.append(s)
+            with self.log_path.open("a") as f:
+                f.write(
+                    "[property-data] tool=property-data-prices account=local postcode=CM232UJ status=ok ms=99\n"
+                )
+
+        _assert_observability_logs(
+            self.log_path,
+            deadline_s=10.0,
+            poll_s=2.0,
+            _now=lambda: next(ticks),
+            _sleep=fake_sleep,
+        )
+        self.assertEqual(appended, [2.0])
+
+    def test_unreadable_log_aborts_at_deadline(self):
+        """A log path that can't be read is treated as missing tools — abort
+        once the budget elapses, name a missing tool. No silent skip."""
+        # Don't write the log file at all.
+        ticks = iter([0.0, 100.0])
+        with self.assertRaises(PrevalAbort) as ctx:
+            _assert_observability_logs(
+                self.log_path,
+                deadline_s=60.0,
+                poll_s=2.0,
+                _now=lambda: next(ticks),
+                _sleep=lambda s: None,
+            )
+        self.assertTrue(ctx.exception.cause.startswith("observability-missing tool="))
+
+
+if __name__ == "__main__":
+    unittest.main()