@pdtf/schemas 3.6.0-dev.1 → 3.6.0-dev.3

package/pensive-tesla-d0d355/docs/branch-release-workflow.md

@@ -0,0 +1,138 @@
+# Branch And Release Workflow
+
+This repository uses three long-lived release channels for `@pdtf/schemas`.
+
+## Branches And npm Tags
+
+| Branch | npm dist-tag | Purpose |
+| --- | --- | --- |
+| `main` | `latest` | Stable PDTF releases for broad industry use. |
+| `next` | `next` | Tested capabilities intended for the next managed PDTF point release. |
+| `dev` | `dev` | Unstable coal face for faster-moving integration work and early adopters. |
+
+`dev` is not the standard. It is a proving ground for changes that may later be
+promoted to `next` through focused PRs. Consumers who need the stable standard
+should use `@pdtf/schemas` from `latest`/`main`.
+
+## Versioning
+
+Every npm publish must have a unique semver version.
+
+- `main` publishes normal release versions, for example `3.5.0`, on `latest`.
+- `next` publishes prerelease versions on the `next` tag.
+- `dev` publishes prerelease versions on the `dev` tag, using a `-dev.N`
+  suffix, for example `3.6.0-dev.0`.
+
+Do not publish `dev` or `next` builds to `latest`.
+
+## Dev Fast-Path Workflow
+
+Use this workflow when work needs to move faster than the managed PDTF release
+cycle, or when a change needs practical integration testing before it is proposed
+for the standards-track path.
+
+1. Open a PR against `dev`.
+2. Treat `dev` as the unstable coal face. Keep the change reviewable and, where
+   possible, structured so that accepted parts can later be promoted to `next`.
+3. Change `src/schemas/v3/combined.json` for schema changes, then run both
+   extraction scripts:
+
+   ```bash
+   npm run extract-overlays
+   npm run extract-extension-overlays
+   ```
+
+4. Add or update tests for schema, overlay, path-validation, and utility
+   behaviour.
+5. Bump the package version to the next unique `-dev.N` version if the PR will
+   be published from `dev`.
+6. If the change should not enter the `next` review queue after it has landed in
+   `dev`, add the `no-promote-next` label before merging.
+7. Merge to `dev`.
+8. If publishing the dev channel, publish from `dev`:
+
+   ```bash
+   npm run publish:dev
+   ```
+
+9. Consumers can use `@pdtf/schemas@dev`, or pin the exact dev version in
+   lockfiles when deterministic rollout is required.
+
+## Automated Promotion To next
+
+The `.github/workflows/promote-dev-to-next.yml` workflow can open the matching
+`next` PR automatically.
+
+Trigger:
+
+- A PR is merged into `dev`.
+- The merged PR does not have the `no-promote-next` label.
+
+Behaviour:
+
+1. Check out `next`.
+2. Create a branch named `promote/dev-pr-<number>-to-next`.
+3. Cherry-pick the merged dev PR's effective diff onto that branch.
+4. Open a PR into `next` with a title and body referencing the original dev PR.
+
+If the cherry-pick conflicts, the workflow creates an issue instead of a PR so a
+maintainer can promote the change manually.
+
+The promotion PR is intentionally still reviewed. Before merging to `next`,
+maintainers should:
+
+- confirm the change is appropriate for the managed release path;
+- remove any dev-only scaffolding;
+- adjust package version metadata from `-dev.N` to the correct `next`
+  prerelease version where needed;
+- run tests and schema extraction checks.
+
+## Manual Promotion To next
+
+If automation is not used, or if the automated cherry-pick conflicts:
+
+1. Branch from `next`.
+2. Cherry-pick the merged dev PR commit or recreate the focused diff.
+3. Remove dev-only changes.
+4. Bump to the next unique `next` prerelease version if the PR will be published
+   from `next`.
+5. Open a PR into `next` that links back to the original dev PR.
+6. Merge to `next` after review.
+7. Publish from `next`:
+
+   ```bash
+   npm run publish:next
+   ```
+
+The `next` channel should remain tested and coherent. It can be ahead of
+`main`, but it should not contain unrelated experimental work merely because it
+exists on `dev`.
+
+## Promotion To main
+
+When the PDTF point-release cycle is ready:
+
+1. Select accepted `next` changes for the point release.
+2. Merge or cherry-pick the accepted changes into `main`.
+3. Bump to the release version, for example `3.6.0`.
+4. Publish from `main`:
+
+   ```bash
+   npm run publish:latest
+   ```
+
+Long-running `dev` work should not be merged wholesale into `main` unless the
+full contents have been reviewed and accepted for the PDTF release.
+
+## Consumer Compatibility Profiles
+
+Consumer-specific compatibility profiles are owned by the consuming application
+or service unless and until they become a reusable PDTF capability.
+
+Consumers may pin exact supplied schemas, hash them, and filter outbound API
+calls or webhooks accordingly. That code should not be added to this schema
+package unless the capability is generic and appropriate for PDTF consumers.
+
+If a consumer later supports an official PDTF release, its target profile should
+move from the consumer-specific schema to the relevant published
+`@pdtf/schemas` release or prerelease.

package/pensive-tesla-d0d355/docs/sef25-extensions-ui-spec.md

@@ -0,0 +1,355 @@
+# SEF25 Extension Overlays — Front-End UI Spec
+
+## Overview
+
+Extension overlays add follow-up questions to existing form sections. Each overlay is loaded by passing its key to `getTransactionSchema(schemaId, overlays)`.
+
+### Pre-existing overlays
+
+These were added before this PR and are already in production.
+
+| Overlay Key | Name | Section | Fields Added |
+|-------------|------|---------|-------------|
+| `sc` | Supply Costs | Water & Drainage | Cost fields for private water and sewerage (restructured to hasCost Yes/No gate) |
+| `pc` | Parking Permit Cost | Parking | 1 frequency field |
+| `ph` | Property Hazards | Specialist Issues | 4 Yes/No + details fields |
+
+### New overlays (this PR)
+
+| Overlay Key | Name | Section | Fields Added |
+|-------------|------|---------|-------------|
+| `dk` | Dropped Kerb | Parking | 1 Yes/No field |
+| `rw` | Private Right of Way | Rights & Informal Arrangements | 1 Yes/No + details field |
+| `sd` | Storm/Fire/Flood Damage | Environmental Issues | 1 Yes/No + details field |
+| `lc` | Solar Lease Costs | Utilities (Solar Panels) | 1 cost field (hasCost + amount + frequency) |
+| `wg` | Warranties & Guarantees | Guarantees & Warranties | Marks 7 warranty categories as required |
+| `ic` | Insurance Claims | Insurance | Marks insuranceClaims required (isInsured=Yes branch) |
+| `nd` | Neighbour Development | Notices | Adds sef25Ref to neighbourDevelopment (already required via NTS) |
+| `mi` | Material Issue | Additional Information | Marks otherMaterialIssue required |
+| `tr` | Title Restrictions | Ownership (Freehold) | Adds titleRestrictions field to freehold branch |
+
+### Existing fields with sef25Ref only (no separate overlay needed)
+
+| Field | Path | sef25Ref | Notes |
+|-------|------|----------|-------|
+| `hasBeenFlooded` | `environmentalIssues.flooding.historicalFlooding.hasBeenFlooded` | E1.2 | Already required and rendered via NTS flooding section |
+
+All fields use `sef25Ref` for reference codes.
+
+---
+
+## Pre-existing overlays (detail)
+
+### 1. Supply Costs (`sc`)
+
+#### 1a. Private Water Cost
+
+**Trigger:** Show when `propertyPack.waterAndDrainage.water.mainsWater.yesNo` = `"No"`
+
+**Path:** `propertyPack.waterAndDrainage.water.mainsWater.associatedCost`
+
+**UI:** Render alongside the existing "How is water supplied?" details field. First ask if there are costs, then show amount and frequency if Yes.
+
+| Field | Path (relative) | Type | Validation | UI Element |
+|-------|-----------------|------|------------|------------|
+| Has costs? | `associatedCost.hasCost` | `string` | Required, enum | Yes/No radio |
+| Cost (£) | `associatedCost.amount` | `number` | Required when Yes | Numeric input |
+| Payment frequency | `associatedCost.frequency` | `string` | Required when Yes, enum | Dropdown |
+
+**Frequency enum values:** `"Per month"`, `"Per year"`
+
+**Ref:** `U1.1` (hasCost: `U1.1.1`, amount: `U1.1.2`, frequency: `U1.1.3`)
+
+#### 1b. Private Sewerage Cost
+
+**Trigger:** Show when `propertyPack.waterAndDrainage.drainage.mainsFoulDrainage.yesNo` = `"No"` or `"Not known"`
+
+**Path:** `propertyPack.waterAndDrainage.drainage.mainsFoulDrainage.associatedCost`
+
+**UI:** Same hasCost pattern as water cost above.
+
+**Ref:** `U1.2` (hasCost: `U1.2.1`, amount: `U1.2.2`, frequency: `U1.2.3`)
+
+### 2. Parking Permit Cost (`pc`)
+
+**Trigger:** Show when `propertyPack.parking.controlledParking.yesNo` = `"Yes"`
+
+**Path:** `propertyPack.parking.controlledParking.costOfPermitFrequency`
+
+**UI:** Render alongside the existing cost of permit field. The frequency dropdown clarifies whether the cost amount is monthly or annual.
+
+| Field | Path (relative) | Type | Validation | UI Element |
+|-------|-----------------|------|------------|------------|
+| Payment frequency | `costOfPermitFrequency` | `string` | Enum | Dropdown |
+
+**Frequency enum values:** `"Per month"`, `"Per year"`
+
+**Ref:** `P1.1`
+
+### 3. Property Hazards (`ph`)
+
+**Trigger:** Always shown (standalone questions within Specialist Issues).
+
+**Path prefix:** `propertyPack.specialistIssues`
+
+All 4 fields follow the same pattern: Yes/No, if Yes show required details.
+
+| Property | Title | sef25Ref |
+|----------|-------|----------|
+| `wellsDitchesShaft` | Are there any wells, ditches, or shafts at the property? | H1.1 |
+| `damagedOrExposedElectrics` | Are there any damaged or exposed electrics at the property? | H1.2 |
+| `damageToFlooringOrStaircases` | Is there any damage to flooring and/or staircases? | H1.3 |
+| `knownAreasInPoorCondition` | Are there any known areas in poor condition (internal or external)? | H1.4 |
+
+---
+
+## New overlays (detail)
+
+### 4. Dropped Kerb (`dk`)
+
+**Trigger:** Always shown within Parking section.
+
+**Path:** `propertyPack.parking.droppedKerbAccess`
+
+| Field | Path (relative) | Type | Validation | UI Element |
+|-------|-----------------|------|------------|------------|
+| Dropped kerb? | `droppedKerbAccess.yesNo` | `string` | Required, enum | Yes/No radio |
+
+**Ref:** `K1.1` (yesNo: `K1.1.1`)
+
+---
+
+### 5. Private Right of Way (`rw`)
+
+**Trigger:** Always shown within Rights & Informal Arrangements, alongside the existing public right of way question.
+
+**Path:** `propertyPack.rightsAndInformalArrangements.rightsOrArrangements.privateRightOfWay`
+
+**UI:** Same pattern as `publicRightOfWay` — Yes/No, if Yes show details.
+
+| Field | Path (relative) | Type | Validation | UI Element |
+|-------|-----------------|------|------------|------------|
+| Private ROW? | `privateRightOfWay.yesNo` | `string` | Required, enum | Yes/No radio |
+| Details | `privateRightOfWay.details` | `string` | Required when Yes, minLength 1 | Text input |
+
+**Ref:** `R1.1` (yesNo: `R1.1.1`, details: `R1.1.2`)
+
+---
+
+### 6. Storm, Fire or Flood Damage (`sd`)
+
+**Trigger:** Always shown within Environmental Issues section.
+
+**Path:** `propertyPack.environmentalIssues.stormFireFloodDamage`
+
+| Field | Path (relative) | Type | Validation | UI Element |
+|-------|-----------------|------|------------|------------|
+| Damage? | `stormFireFloodDamage.yesNo` | `string` | Required, enum | Yes/No radio |
+| Details | `stormFireFloodDamage.details` | `string` | Required when Yes, minLength 1 | Text area |
+
+**Ref:** `E1.1` (yesNo: `E1.1.1`, details: `E1.1.2`)
+
+---
+
+### 7. Solar Panel Lease Costs (`lc`)
+
+**Trigger:** Show when `propertyPack.electricity.solarPanels.panelsOwnedOutright.yesNo` = `"No"` (panels are leased).
+
+**Path:** `propertyPack.electricity.solarPanels.panelsOwnedOutright.associatedCost`
+
+**UI:** Render alongside existing lease details. First ask if there are costs, then show amount and frequency if Yes.
+
+| Field | Path (relative) | Type | Validation | UI Element |
+|-------|-----------------|------|------------|------------|
+| Has costs? | `associatedCost.hasCost` | `string` | Required, enum | Yes/No radio |
+| Amount (£) | `associatedCost.amount` | `number` | Required when Yes | Numeric input |
+| Frequency | `associatedCost.frequency` | `string` | Required when Yes, enum | Dropdown |
+
+**Frequency enum values:** `"Per month"`, `"Per year"`
+
+**Ref:** `S1.1` (hasCost: `S1.1.1`, amount: `S1.1.2`, frequency: `S1.1.3`)
+
+---
+
+### 8. Warranties & Guarantees Upfront (`wg`)
+
+**Trigger:** Always shown when overlay is loaded. Displayed upfront regardless of `hasValidGuaranteesOrWarranties` value.
+
+**Path prefix:** `propertyPack.guaranteesWarrantiesAndIndemnityInsurances`
+
+**UI:** For SEF25 upfront, show all 7 warranty categories as simple Yes/No questions. No details or "Years Remaining" needed at this stage — the law firm picks up details later.
+
+| Property | Title | sef25Ref |
+|----------|-------|----------|
+| `newHomeWarranty` | New Home Warranty (NHBC or similar) | W1.1 |
+| `roofingWork` | Roofing work | W1.2 |
+| `dampProofingTreatment` | Damp proofing treatment | W1.3 |
+| `centralHeatingAndorPlumbing` | Central heating and/or plumbing | W1.4 |
+| `electricalRepairOrInstallation` | Electrical repair or installation | W1.5 |
+| `subsidenceWork` | Underpinning or other preventative work / remedial action relating to subsidence | W1.6 |
+| `otherGuarantees` | Other Guarantees or warranties | W1.7 |
+
+**Note:** These fields already exist in the base schema under the `hasValidGuaranteesOrWarranties = "Yes"` branch. The `wg` overlay marks them as required within that branch. The Moverly app shows them upfront for SEF25 users without requiring the parent gate question first.
+
+---
+
+### 9. Insurance Claims (`ic`)
+
+**Path:** `propertyPack.insurance.insuranceClaims` (inside `isInsured = "Yes"` branch)
+
+**Ref:** `I1.1` (yesNo: `I1.1.1`) — "Have you made any buildings insurance claims?"
+
+**Note:** The overlay marks insuranceClaims required within the `isInsured = "Yes"` oneOf branch.
+
+---
+
+### 10. Neighbour Development (`nd`)
+
+**Path:** `propertyPack.notices.neighbourDevelopment`
+
+**Ref:** `N1.1` — "Is the seller aware of any proposals to develop property or land nearby?"
+
+**Note:** `neighbourDevelopment` is already required via `ntsRequired` at the notices level. The `nd` overlay adds `sef25Ref` and `ntsRef` annotations so the field is identifiable as SEF25-relevant.
+
+---
+
+### 11. Material Issue (`mi`)
+
+**Path:** `propertyPack.additionalInformation.otherMaterialIssue`
+
+**Ref:** `M1.1` (yesNo: `M1.1.1`) — "Are you aware of any other material issue or information which may affect the average person's decision to proceed?"
+
+---
+
+### 12. Title Restrictions (`tr`)
+
+**Path:** `propertyPack.ownership.ownershipsToBeTransferred[Freehold].titleRestrictions`
+
+**Ref:** `T1.1` (yesNo: `T1.1.1`, details: `T1.1.2`) — "Are there any known restrictions on the title?"
+
+New field on the freehold ownership branch, modelled on `leaseRestrictions` for leasehold. Yes/No + details if Yes.
+
+---
+
+## Loading the Extensions
+
+```js
+import { getTransactionSchema, getValidator } from "@pdtf/schemas";
+
+const schemaId = "https://trust.propdata.org.uk/schemas/v3/pdtf-transaction.json";
+
+// Load all SEF25 extensions
+const sef25Extensions = ["sc", "pc", "ph", "dk", "rw", "sd", "lc", "wg", "ic", "nd", "mi", "tr"];
+const schema = getTransactionSchema(schemaId, sef25Extensions);
+
+// Or combine with other overlays
+const schema = getTransactionSchema(schemaId, ["baspiV5", ...sef25Extensions]);
+
+// Validate data against the merged schema
+const validator = getValidator(schemaId, sef25Extensions);
+```
+
+---
+
+## Summary of Trigger Conditions
+
+| Field | Visible when... |
+|-------|----------------|
+| Water cost | `mainsWater.yesNo` = `"No"` |
+| Sewerage cost | `mainsFoulDrainage.yesNo` = `"No"` or `"Not known"` |
+| Parking permit frequency | `controlledParking.yesNo` = `"Yes"` |
+| Wells/ditches/shaft | Always (within Specialist Issues) |
+| Damaged electrics | Always (within Specialist Issues) |
+| Flooring/staircase damage | Always (within Specialist Issues) |
+| Areas in poor condition | Always (within Specialist Issues) |
+| Dropped kerb access | Always (within Parking) |
+| Private right of way | Always (within Rights & Informal Arrangements) |
+| Storm/fire/flood damage | Always (within Environmental Issues) |
+| Solar panel lease costs | `panelsOwnedOutright.yesNo` = `"No"` |
+| Warranty categories (7) | Always when `wg` overlay loaded (within Guarantees & Warranties) |
+| Insurance claims | `isInsured.yesNo` = `"Yes"` (via `ic` overlay) |
+| Neighbour development | Always (via `nd` overlay) |
+| Other material issue | Always (via `mi` overlay) |
+| Title restrictions | Always (via `tr` overlay, freehold only) |
+
+---
+
+## Moverly propertyPackTasks Changes
+
+The following changes are needed in the Moverly app's `propertyPackTasks` configuration to surface the new SEF25 fields in the listing journey.
+
+### Existing tasks to deprecate
+
+The flooding and planning tasks should be stepped up to their parent section level to cover the new sibling fields (`stormFireFloodDamage` and `neighbourDevelopment`).
+
+```js
+// Replace existing flooding task with deprecated version
+{
+  name: "Flooding",
+  path: "/propertyPack/environmentalIssues/flooding",
+  category: "listing",
+  overlay: "nts2023",
+  deprecated: true, // replaced by environmental issues check
+},
+
+// Replace existing planning task with deprecated version
+{
+  name: "Planning and development",
+  path: "/propertyPack/notices/planningApplication",
+  category: "listing",
+  overlay: "nts2023",
+  deprecated: true, // replaced by notices check
+},
+```
+
+### New listing tasks to add
+
+```js
+{
+  name: "Environmental issues",
+  checkName: "sef25-environmentalIssues",
+  path: "/propertyPack/environmentalIssues",
+  category: "listing",
+  overlay: "sd",
+},
+{
+  name: "Notices",
+  checkName: "sef25-notices",
+  path: "/propertyPack/notices",
+  category: "listing",
+  overlay: "nd",
+},
+{
+  name: "Guarantees & warranties",
+  checkName: "sef25-warranties",
+  path: "/propertyPack/guaranteesWarrantiesAndIndemnityInsurances",
+  category: "listing",
+  overlay: "wg",
+},
+{
+  name: "Insurance claims",
+  checkName: "sef25-insurance",
+  path: "/propertyPack/insurance",
+  category: "listing",
+  overlay: "ic",
+},
+{
+  name: "Additional material information",
+  checkName: "sef25-additionalInformation",
+  path: "/propertyPack/additionalInformation",
+  category: "listing",
+  overlay: "mi",
+},
+```
+
+### Fields covered by existing listing tasks (no new task needed)
+
+| Extension | Covered by |
+|-----------|------------|
+| `dk` (dropped kerb) | Parking |
+| `rw` (private right of way) | Rights and easements |
+| `lc` (solar lease costs) | Electricity |
+| `sc` (supply costs) | Water and drainage |
+| `pc` (parking permit cost) | Parking |
+| `ph` (property hazards) | Specialist issues |
+| `tr` (title restrictions) | Ownership |