@pdtf/schemas 3.6.0-dev.4 → 3.6.0-dev.6

package/compassionate-easley-bafb14/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/{keen-dewdney-6ae15b → compassionate-easley-bafb14}/README.md

@@ -7,18 +7,25 @@ The Property Data Trust Framework (PDTF) Schemas provide standardized JSON Schem
 
 ## Project Goals & Status
 
-**Current Version:** 3.4.0 (Schema v3 - Stable)
+**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  
+- 🔗 **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
 
@@ -35,7 +42,7 @@ npm install @pdtf/schemas
 ### Basic Usage
 
 ```javascript
-const { getTransactionSchema, getValidator } = require('@pdtf/schemas');
+const { getTransactionSchema, getValidator } = require("@pdtf/schemas");
 
 // Get a schema with BASPI v5 overlay
 const schema = getTransactionSchema(
@@ -45,14 +52,14 @@ const schema = getTransactionSchema(
 
 // Create a validator
 const validator = getValidator(
-  "https://trust.propdata.org.uk/schemas/v3/pdtf-transaction.json", 
+  "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);
+  console.log("Validation errors:", validator.errors);
 }
 ```
 
@@ -60,7 +67,7 @@ if (!isValid) {
 
 - **🏗️ Modular Schema System** - Base schemas with flexible overlay composition
 - **📋 Multiple Form Support** - BASPI, NTS, Law Society TA forms, and more
-- **🧩 Extension Overlays** - Granular NTS2 features as individual modules
+- **🧩 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
@@ -80,7 +87,7 @@ if (!isValid) {
 │   │   │   │   └── extensions/        # Modular NTS2 extensions
 │   │   │   │       ├── jk.json        # Japanese Knotweed
 │   │   │   │       ├── tf.json        # Transfer Fees
-│   │   │   │       └── ...            # 16 total extensions
+│   │   │   │       └── ...            # NTS2 + SEF25 extensions
 │   │   │   └── combined.json          # Master schema for generation
 │   │   ├── v2/                        # Legacy schema version
 │   │   ├── verifiedClaims/            # Verified claims schemas
@@ -122,6 +129,7 @@ const schema = getTransactionSchema(
 ```
 
 **Parameters:**
+
 - `schemaId` (string): Schema version URL
 - `overlays` (array): Array of overlay names or objects
 
@@ -146,39 +154,70 @@ const errors = validateVerifiedClaims(verifiedClaims, schemaId, ["nts2023"]);
 
 #### 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 |
+| 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 NTS2 features for selective adoption:
+Modular features for selective adoption. Extensions are merged on top of an NTS base overlay.
 
 ```javascript
-// Individual extensions
-const schema = getTransactionSchema(schemaId, ["nts2023", "jk", "tf"]);
+// NTS2 extensions
+const schema = getTransactionSchema(schemaId, ["nts2023", "jk", "tf", "ma"]);
 
-// Multiple specialist issues
-const schema = getTransactionSchema(schemaId, ["nts2023", "as", "dr", "jk", "sb"]);
+// 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 |
-| Transfer Fees | `tf` | Additional leasehold fees |
-| Managing Agent | `ma` | Leasehold managing agent details |
-| Solar Panels | `sl` | Solar panel ownership details |
 | 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 |
 
-[View all extensions →](src/schemas/v3/overlays/README.md#extension-overlays)
+**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
 
@@ -195,27 +234,26 @@ const legalSchema = getTransactionSchema(schemaId, ["ta6ed4", "ta7ed3"]);
 const ntsSchema = getTransactionSchema(schemaId, ["nts2023"]);
 ```
 
-### Modular NTS2 Features
+### Modular Extension Features
 
 ```javascript
 // Selective NTS2 adoption
 const partialNts2 = getTransactionSchema(schemaId, [
-  "nts2023",        // Base NTS
-  "jk",             // Japanese Knotweed
-  "tf",             // Transfer Fees  
-  "ma"              // Managing Agent
+  "nts2023", // Base NTS
+  "jk", // Japanese Knotweed
+  "tf", // Transfer Fees
+  "ma", // Managing Agent
 ]);
 
-// Full specialist issues
-const specialistIssues = getTransactionSchema(schemaId, [
-  "nts2023", "as", "dr", "jk", "sb", "hs"
-]);
+// 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 { getValidator } = require("@pdtf/schemas");
 
 const validator = getValidator(schemaId, ["baspiV5"]);
 
@@ -223,16 +261,16 @@ const propertyData = {
   propertyPack: {
     priceInformation: {
       price: 350000,
-      priceQualifier: "Freehold"
+      priceQualifier: "Freehold",
     },
     // ... more property data
-  }
+  },
 };
 
 if (validator(propertyData)) {
-  console.log('✅ Data is valid');
+  console.log("✅ Data is valid");
 } else {
-  console.log('❌ Validation errors:', validator.errors);
+  console.log("❌ Validation errors:", validator.errors);
 }
 ```
 
@@ -241,46 +279,110 @@ if (validator(propertyData)) {
 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');
+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" }
-    }]
+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",
+    },
   },
-  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');
+  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
@@ -311,17 +413,17 @@ 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). 
+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.
 
@@ -331,4 +433,3 @@ Licensed under the [MIT License](https://opensource.org/licenses/MIT).
 - 📁 [Example Files](src/examples/)
 - 🐛 [Issue Tracker](https://github.com/Property-Data-Trust-Framework/schemas/issues)
 - 🌐 [PDTF Website](https://trust.propdata.org.uk)
-

package/compassionate-easley-bafb14/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.