@pdtf/schemas 3.6.0-dev.7 → 3.6.0-dev.8

package/busy-spence-79c6bf/CLAUDE.md

@@ -0,0 +1,101 @@
+# CLAUDE.md
+
+This file provides guidance for AI coding agents when working with code in this repository.
+
+## Overview
+
+This repository contains the Property Data Trust Framework (PDTF) schemas - JSON Schema-based definitions for digital residential property data exchange in England and Wales. The framework enables frictionless exchange of property data between software products and services.
+
+## Commands
+
+### Testing
+```bash
+npm test          # Run all tests
+npm run test:watch # Run tests in watch mode
+```
+
+### Development
+```bash
+npm install                       # Install dependencies
+npm run extract-overlays          # Regenerate v3 schemas and overlays from combined.json
+npm run extract-extension-overlays # Regenerate v3 extension overlays from combined.json
+npm run publish:dev               # Publish the dev branch package to npm tag dev
+npm run publish:next              # Publish the next branch package to npm tag next
+npm run publish:latest            # Publish the main branch package to npm tag latest
+```
+
+**Important**: `src/schemas/v3/combined.json` is the source of truth for v3 schema changes. Never edit generated schema artifacts directly; there are no exceptions. Utility/source files may be edited normally. After changing `combined.json`, always run both overlay extraction commands so derived files stay in sync.
+
+## Architecture
+
+### Schema System
+The PDTF uses a flexible overlay system where a base transaction schema can be extended with form-specific overlays:
+
+- **Base Schema**: Core transaction schema at `/src/schemas/v3/pdtf-transaction.json`
+- **Overlays**: Form-specific extensions in `/src/schemas/v3/overlays/` (e.g., baspi5.json, ta6.json)
+- **Merging**: Overlays are merged with the base schema using deepmerge with custom merge strategies
+- **Generated Files**: `pdtf-transaction.json`, `skeleton.json`, `compactSkeleton.txt`, `src/schemas/v3/overlays/*.json`, and `src/schemas/v3/overlays/extensions/*.json` are generated from `combined.json`
+
+### Key Components
+
+1. **index.js**: Main module exposing schema utilities
+   - `getTransactionSchema(schemaId, overlays)`: Merges base schema with overlays
+   - `getValidator(schemaId, overlays)`: Returns AJV validator for schema
+   - `validateVerifiedClaims()`: Validates verified claims structure
+
+2. **Schema Versions**: Currently on v3, with v2 still supported
+   - Use `https://trust.propdata.org.uk/schemas/v3/pdtf-transaction.json` for v3
+
+3. **Overlay System**: Supports multiple UK property forms
+   - BASPI (v4 and v5)
+   - Law Society TA forms (TA6, TA7, TA10)
+   - NTS forms (2023 and 2025 versions)
+   - CON29R, PIQ, RDS, and others
+
+### Testing Approach
+Tests in `/src/tests/` validate:
+- Schema structure with different overlay combinations
+- Path validation for nested properties
+- Custom overlay merging
+- Verified claims validation
+
+Use existing test patterns when adding new tests.
+
+## Branch And Release Workflow
+
+This repository publishes `@pdtf/schemas` through three branches and npm
+dist-tags:
+
+- `main` -> npm `latest`: stable PDTF releases for broad industry use.
+- `next` -> npm `next`: tested capabilities proposed for the next managed PDTF
+  point release.
+- `dev` -> npm `dev`: the unstable coal face for faster-moving integration work
+  and early adopters.
+
+PRs may be merged into `dev` to prove out work before it is ready for the managed
+release path. Once a `dev` PR has been tested and is suitable for standards
+review, promote the same change into `next` via a focused PR. Do not treat `dev`
+as the standard, and do not publish `dev` or `next` builds to npm `latest`.
+
+Promotion is automatic by default: after a PR is merged into `dev`,
+`.github/workflows/promote-dev-to-next.yml` creates a matching PR into `next` by
+cherry-picking the merged dev PR. Add the `no-promote-next` label before merging
+a dev PR only when it should stay out of the `next` review queue. Reviewers
+should still inspect the promotion PR, resolve conflicts, and adjust
+release/version metadata if needed before merging to `next`.
+
+Each npm publish needs a unique semver version. Use `-dev.N` versions on `dev`,
+prerelease versions on `next`, and normal release versions on `main`.
+
+Consumer-specific compatibility profiles belong in the consuming application or
+service unless the capability becomes generic PDTF package functionality.
+Consumers should pin/hash supplied schemas and use their own target-profile
+configuration for API calls and webhooks.
+
+See `docs/branch-release-workflow.md` for the full workflow.
+
+## Important Notes
+
+- All schemas use JSON Schema Draft 07
+- The repository publishes to npm as `@pdtf/schemas`
+- Overlays may contain fields from licensed forms (BASPI, PIQ, Law Society) - ensure compliance when rendering data

package/busy-spence-79c6bf/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Property Data Trust Framework
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/busy-spence-79c6bf/README.md

@@ -0,0 +1,435 @@
+# PDTF Schemas
+
+[![npm version](https://badge.fury.io/js/%40pdtf%2Fschemas.svg)](https://badge.fury.io/js/%40pdtf%2Fschemas)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+The Property Data Trust Framework (PDTF) Schemas provide standardized JSON Schema definitions for digital residential property data exchange in England and Wales. This package enables frictionless property data exchange between software products and services while maintaining trusted information about data provenance.
+
+## Project Goals & Status
+
+**Current Version:** 3.5.0 on `main` / npm `latest`.
+
+Additional release channels are available for earlier adoption:
+
+- `next` branch / npm `next`: tested capabilities proposed for the next PDTF release.
+- `dev` branch / npm `dev`: fast-moving integration work for Moverly and other early adopters. This channel may include changes that are not yet accepted as PDTF standard capability.
+
+This schema framework aims to support the [Home Buying and Selling Group](https://homebuyingandsellinggroup.co.uk) 'Property Pack' initiative, encompassing all requirements starting with the Buyers and Sellers Property Information set ([BASPI v4.0](https://homebuyingandsellinggroup.co.uk/baspi/)).
+
+**Key Objectives:**
+
+- 🏠 **Standardize** residential property data exchange across England and Wales
+- 🔗 **Enable** frictionless data sharing between software products and services
+- 🛡️ **Maintain** trusted information about data provenance and verification
+- 📋 **Support** industry-standard forms (BASPI, NTS, Law Society TA forms)
+- 🧩 **Provide** modular components for flexible implementation
+
+**Related Projects:**
+
+- [API Specifications](https://github.com/Property-Data-Trust-Framework/api) - OpenAPI specs for data exchange protocols
+- [PDTF Website](https://trust.propdata.org.uk) - Official framework documentation
+
+This repository is a living document, with schemas evolving as framework requirements are refined and extended. Semantic versioning ensures backward compatibility while enabling schema evolution.
+
+## Quick Start
+
+### Installation
+
+```bash
+npm install @pdtf/schemas
+```
+
+### Basic Usage
+
+```javascript
+const { getTransactionSchema, getValidator } = require("@pdtf/schemas");
+
+// Get a schema with BASPI v5 overlay
+const schema = getTransactionSchema(
+  "https://trust.propdata.org.uk/schemas/v3/pdtf-transaction.json",
+  ["baspiV5"]
+);
+
+// Create a validator
+const validator = getValidator(
+  "https://trust.propdata.org.uk/schemas/v3/pdtf-transaction.json",
+  ["baspiV5"]
+);
+
+// Validate data
+const isValid = validator(propertyData);
+if (!isValid) {
+  console.log("Validation errors:", validator.errors);
+}
+```
+
+## Features
+
+- **🏗️ Modular Schema System** - Base schemas with flexible overlay composition
+- **📋 Multiple Form Support** - BASPI, NTS, Law Society TA forms, and more
+- **🧩 Extension Overlays** - Granular NTS2 and SEF25 features as individual modules
+- **✅ JSON Schema Validation** - Full JSON Schema Draft 07 support with AJV
+- **🔗 Verified Claims** - Support for verified data provenance tracking
+- **📚 Comprehensive Documentation** - Detailed usage guides and examples
+
+## Package Structure
+
+```
+@pdtf/schemas/
+├── src/
+│   ├── schemas/
+│   │   ├── v3/                    # Current schema version
+│   │   │   ├── pdtf-transaction.json    # Base transaction schema
+│   │   │   ├── overlays/               # Form-specific overlays
+│   │   │   │   ├── baspi5.json        # BASPI v5 overlay
+│   │   │   │   ├── nts.json           # National Trading Standards
+│   │   │   │   ├── ta6.json           # Law Society forms
+│   │   │   │   └── extensions/        # Modular NTS2 extensions
+│   │   │   │       ├── jk.json        # Japanese Knotweed
+│   │   │   │       ├── tf.json        # Transfer Fees
+│   │   │   │       └── ...            # NTS2 + SEF25 extensions
+│   │   │   └── combined.json          # Master schema for generation
+│   │   ├── v2/                        # Legacy schema version
+│   │   ├── verifiedClaims/            # Verified claims schemas
+│   │   └── examples/                  # Example data files
+│   ├── tests/                         # Jest test suite
+│   └── utils/                         # Build and extraction tools
+├── index.js                          # Main API entry point
+└── package.json
+```
+
+## Core Concepts
+
+### Base Schema + Overlays
+
+PDTF uses a **base transaction schema** combined with **overlays** to create form-specific schemas:
+
+- **Base Schema**: Core property transaction structure
+- **Overlays**: Form-specific fields, references, and validation rules
+- **Extensions**: Modular components for selective feature adoption
+
+### Schema Versions
+
+- **v3** (Current): Full feature set with extension support
+- **v2** (Legacy): Maintained for backward compatibility
+
+## API Reference
+
+### Core Functions
+
+#### `getTransactionSchema(schemaId, overlays)`
+
+Creates a merged schema from base schema and overlays.
+
+```javascript
+const schema = getTransactionSchema(
+  "https://trust.propdata.org.uk/schemas/v3/pdtf-transaction.json",
+  ["baspiV5", "ta6ed4"]
+);
+```
+
+**Parameters:**
+
+- `schemaId` (string): Schema version URL
+- `overlays` (array): Array of overlay names or objects
+
+#### `getValidator(schemaId, overlays)`
+
+Returns an AJV validator function for the specified schema combination.
+
+```javascript
+const validator = getValidator(schemaId, ["baspiV5"]);
+const isValid = validator(data);
+```
+
+#### `validateVerifiedClaims(claims, schemaId, overlays)`
+
+Validates verified claims against schema paths.
+
+```javascript
+const errors = validateVerifiedClaims(verifiedClaims, schemaId, ["nts2023"]);
+```
+
+### Available Overlays
+
+#### Main Form Overlays
+
+| Overlay   | Description                             | Version   |
+| --------- | --------------------------------------- | --------- |
+| `baspiV4` | Buyers and Sellers Property Information | v4.0      |
+| `baspiV5` | Buyers and Sellers Property Information | v5.0      |
+| `nts2023` | National Trading Standards              | 2023      |
+| `nts2025` | National Trading Standards              | 2025      |
+| `ta6ed4`  | Law Society Property Information Form   | Edition 4 |
+| `ta7ed3`  | Law Society Leasehold Information Form  | Edition 3 |
+| `ta10ed3` | Law Society Fittings and Contents Form  | Edition 3 |
+
+[View all overlays →](src/schemas/v3/overlays/README.md)
+
+#### Extension Overlays
+
+Modular features for selective adoption. Extensions are merged on top of an NTS base overlay.
+
+```javascript
+// NTS2 extensions
+const schema = getTransactionSchema(schemaId, ["nts2023", "jk", "tf", "ma"]);
+
+// SEF25 extensions (Seller Enquiry Form)
+const sef25 = ["sc", "pc", "ph", "dk", "rw", "sd", "lc", "wg", "ic", "nd", "mi", "tr"];
+const schema = getTransactionSchema(schemaId, ["nts2023", ...sef25]);
+```
+
+**NTS2 Extensions:**
+
+| Extension | Code | Description |
+| --- | --- | --- |
+| Japanese Knotweed | `jk` | Knotweed presence and management |
+| Asbestos | `as` | Asbestos presence and management |
+| Dry Rot | `dr` | Dry rot treatment |
+| Subsidence | `sb` | Subsidence or structural fault |
+| Health & Safety | `hs` | Ongoing health or safety issues |
+| Outside Areas | `oa` | Outside areas details |
+| Main Construction | `mc` | Construction type if standard form |
+| Loft Access | `la` | Loft access and details |
+| Spray Foam | `sf` | Spray foam insulation |
+| Solar Panels | `sl` | Solar panel ownership details |
+| Heating Installed | `hi` | Central heating installation date |
+| Flood Defences | `fd` | Flood defence information |
+| Estate Rentcharges | `er` | Estate rentcharges for freehold |
+| Managing Agent | `ma` | Leasehold managing agent details |
+| Transfer Fees | `tf` | Additional leasehold fees |
+| Onward Chain | `oc` | Other property in chain |
+
+**SEF25 Extensions (Seller Enquiry Form):**
+
+| Extension | Code | Description |
+| --- | --- | --- |
+| Supply Costs | `sc` | Private water/sewerage costs |
+| Parking Permit Cost | `pc` | Parking permit frequency |
+| Property Hazards | `ph` | 4 hazard Yes/No questions |
+| Dropped Kerb | `dk` | Dropped kerb access to parking |
+| Private Right of Way | `rw` | Private right of way |
+| Storm/Fire/Flood Damage | `sd` | Storm, fire or flood damage |
+| Solar Lease Costs | `lc` | Solar panel lease costs |
+| Warranties & Guarantees | `wg` | 7 warranty categories upfront |
+| Insurance Claims | `ic` | Insurance claims upfront |
+| Neighbour Development | `nd` | Neighbour development |
+| Material Issue | `mi` | Other material issue upfront |
+| Title Restrictions | `tr` | Title restrictions for freehold |
+
+[View full SEF25 UI spec →](docs/sef25-extensions-ui-spec.md) | [View all extensions →](src/schemas/v3/overlays/README.md#extension-overlays)
+
+## Usage Examples
+
+### Form-Specific Schemas
+
+```javascript
+// BASPI v5 for estate agents
+const baspiSchema = getTransactionSchema(schemaId, ["baspiV5"]);
+
+// Law Society conveyancing forms
+const legalSchema = getTransactionSchema(schemaId, ["ta6ed4", "ta7ed3"]);
+
+// National Trading Standards compliance
+const ntsSchema = getTransactionSchema(schemaId, ["nts2023"]);
+```
+
+### Modular Extension Features
+
+```javascript
+// Selective NTS2 adoption
+const partialNts2 = getTransactionSchema(schemaId, [
+  "nts2023", // Base NTS
+  "jk", // Japanese Knotweed
+  "tf", // Transfer Fees
+  "ma", // Managing Agent
+]);
+
+// SEF25 Seller Enquiry Form extensions
+const sef25 = ["sc", "pc", "ph", "dk", "rw", "sd", "lc", "wg", "ic", "nd", "mi", "tr"];
+const sellerEnquiry = getTransactionSchema(schemaId, ["nts2023", ...sef25]);
+```
+
+### Data Validation
+
+```javascript
+const { getValidator } = require("@pdtf/schemas");
+
+const validator = getValidator(schemaId, ["baspiV5"]);
+
+const propertyData = {
+  propertyPack: {
+    priceInformation: {
+      price: 350000,
+      priceQualifier: "Freehold",
+    },
+    // ... more property data
+  },
+};
+
+if (validator(propertyData)) {
+  console.log("✅ Data is valid");
+} else {
+  console.log("❌ Validation errors:", validator.errors);
+}
+```
+
+### Verified Claims & Data Provenance
+
+PDTF supports verified claims to maintain data provenance and trust throughout property transactions. Claims package specific property data with verification evidence, enabling traceability back to authoritative sources.
+
+```javascript
+const { validateVerifiedClaims } = require("@pdtf/schemas");
+
+// Current verified claims format
+const verifiedClaims = [
+  {
+    id: "claim-12345",
+    transactionId: "txn-67890",
+    schemaVersion: "3.4.0",
+    verification: {
+      trust_framework: "uk_pdtf",
+      time: "2024-07-01T10:30:00Z",
+      evidence: [
+        {
+          type: "vouch",
+          attestation: {
+            type: "digital_attestation",
+            voucher: { name: "Estate Agent Ltd" },
+          },
+          verification_method: { type: "auth" },
+        },
+      ],
+    },
+    terms_of_use: {
+      confidentiality_level: "public",
+    },
+    claims: {
+      "/propertyPack/priceInformation/price": 350000,
+      "/propertyPack/energyEfficiency/epcRating": "C",
+    },
+  },
+];
+
+// Validate claims against schema
+const errors = validateVerifiedClaims(verifiedClaims, schemaId, ["baspiV5"]);
+if (errors.length === 0) {
+  console.log("✅ Verified claims are valid");
+}
+```
+
+**Key Features:**
+
+- **Schema Path Validation** - Claims reference specific schema paths (e.g., `/propertyPack/priceInformation/price`)
+- **Provenance Tracking** - Each claim includes verification evidence and source attribution
+- **Trust Framework Integration** - Claims operate within the UK PDTF trust framework
+- **Attachment Support** - Supporting documents can be cryptographically linked to claims
+- **Confidentiality Controls** - Terms of use define access levels and permitted recipients
+
+#### Confidentiality Levels
+
+Verified claims support three confidentiality levels through a pdtf-specific extension: a `terms_of_use` field, enabling fine-grained access control:
+
+**Public Data** - Freely accessible data from official sources or public listing information:
+
+```javascript
+{
+  terms_of_use: {
+    confidentiality_level: "public";
+  }
+}
+```
+
+Examples: Land Registry data, Energy Performance Certificates, planning records, council tax information
+
+**Restricted Data** - Limited to transaction participants:
+
+```javascript
+{
+  terms_of_use: {
+    confidentiality_level: "restricted";
+  }
+}
+```
+
+Examples: Commercial property reports, contents of legal forms
+
+**Confidential Data** - Role-based access with explicit authorization:
+
+```javascript
+{
+  terms_of_use: {
+    confidentiality_level: "confidential",
+    allowed_roles: [
+      "Estate Agent",
+      "Seller's Conveyancer",
+      "Buyer's Conveyancer",
+      "Mortgage Broker",
+      "Lender"
+    ]
+  }
+}
+```
+
+Examples: Identity verification reports, anti-money laundering checks, sensitive personal information
+
+**Guidelines:**
+
+- Use **public** for government/official data sources
+- Use **restricted** for commercial data providers and processed information
+- Use **confidential** for sensitive personal data requiring explicit role authorization
+- Always consider data source and sensitivity when assigning levels
+
+**Roadmap - W3C Verifiable Credentials:**
+The next version of the PDTF framework will migrate to [W3C Verifiable Credentials](https://www.w3.org/TR/vc-data-model/) to provide:
+
+- **Enhanced Security** - Cryptographically signed claims with tamper detection
+- **Granular Permissions** - Fine-grained access control over claim data
+- **Interoperability** - Standards-based approach for broader ecosystem compatibility
+- **Selective Disclosure** - Share only necessary claim data for each transaction context
+
+## Development
+
+### Building Schemas
+
+Schemas are generated from a master `combined.json` file:
+
+```bash
+# Extract overlays and base schema
+node src/utils/extractOverlay.js
+
+# Generate extension overlays
+node src/utils/extractExtensionOverlays.js
+```
+
+### Testing
+
+```bash
+# Run all tests
+npm test
+
+# Test specific functionality
+npm test -- --testPathPattern=extensionOverlays
+npm test -- --testPathPattern=transactionSchema
+```
+
+## Versioning
+
+The schema follows semantic versioning:
+
+- **Patch** (3.4.x): Bug fixes, no breaking changes
+- **Minor** (3.x.0): New fields, backward compatible
+- **Major** (x.0.0): Breaking changes, migration required
+
+## Licensing
+
+Licensed under the [MIT License](https://opensource.org/licenses/MIT).
+
+**Important:** Overlays contain fields from licensed forms ([BASPI](https://homebuyingsellingcouncil.co.uk/wp-content/uploads/2021/03/Terms-of-Licence-mandatory-download-for-use-of-BASPI.pdf), [PIQ](https://www.propertymark.co.uk/static/14e7c154-98de-4230-957f09bd8d5ddeec/f542b10a-7710-4c37-b3958ccaeec25d4b/property-information-questionnaire-residential-sales.pdf), [Law Society TA](https://www.lawsociety.org.uk/topics/property/transaction-forms)). When rendering data into these forms, ensure compliance with their respective license terms.
+
+## Support
+
+- 📖 [Overlay Documentation](src/schemas/v3/overlays/README.md)
+- 📁 [Example Files](src/examples/)
+- 🐛 [Issue Tracker](https://github.com/Property-Data-Trust-Framework/schemas/issues)
+- 🌐 [PDTF Website](https://trust.propdata.org.uk)

package/busy-spence-79c6bf/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.