Merged PR 2443: added docs

added docs

Related work items: #23754

GUARDRAILS.md

@@ -78,6 +78,8 @@ Minimum required before merge:
 
 - `.clinerules`
 - `CONTRIBUTING_AI.md`
+- `context/implementation-governance.md`
+- `context/maintainability-adoption-programme.md`
 - `context/runbook.md`
 - `context/integration-map.md`
 - `memory-bank/README.md`

context/architecture.md

@@ -30,6 +30,27 @@ Portal authorization hardening / consistency planning (documentation-first, impl
 - preserve stable authorization architecture model
 - use the model as a baseline for future hardening/change review
 
+## Portal Business Capability Context
+
+PEDW Portal should be understood as supporting two principal business capabilities:
+
+1. **Digital Appeal Submission**
+    - currently applies to supported digital appeal processes only
+    - current MVP implementation scope is Section 78 (`S78`)
+    - may be extended in future to additional supported appeal processes
+
+2. **Statutory Public Information & Public Participation**
+    - the portal surfaces CRM-managed statutory case information to the public
+    - includes case details, documents, progress, events, and participation routes where applicable
+    - applies across multiple statutory case types, not only appeal-submission journeys
+
+Business responsibility clarification:
+
+- CRM / PEDW administers the statutory planning and casework processes
+- the portal provides the statutory public-facing digital service layer
+
+This architectural reference builds on those business concepts but does not replace the more detailed terminology guide in `context/business-domain-overview.md`.
+
 ## Portal API Platform Assessment Status (2026-06-20)
 
 ### Stream status

context/business-domain-overview.md

@@ -0,0 +1,279 @@
+# Business Domain Overview
+
+## Purpose
+
+This document provides a concise overview of the principal PEDW planning-domain concepts used throughout the portal.
+
+It is intended for developers and architects who may be unfamiliar with UK and Welsh planning terminology.
+
+It explains business terminology, statutory context, and PEDW portal responsibilities.
+
+It does **not** define software architecture.
+
+The architecture documents build upon these business concepts.
+
+---
+
+## PEDW Portal Business Purpose
+
+PEDW Portal currently supports two broad business capabilities.
+
+## 1. Digital Appeal Services
+
+The portal supports digital services for certain statutory planning appeal processes.
+
+### Current Scope
+
+- Section 78 (`S78`) appeal submission is implemented as the current MVP digital appeal flow.
+
+### Long-Term Direction
+
+The portal may be extended to support additional statutory planning appeal processes where PEDW chooses to offer digital services.
+
+These services may include:
+
+- appeal submission
+- draft management
+- supporting evidence upload
+- validation
+- progress tracking
+
+The exact capabilities available depend upon the statutory appeal process being supported.
+
+### Business Meaning
+
+These are statutory appeals made against decisions of a Local Planning Authority.
+
+For supported appeal processes, the portal provides structured digital services allowing an appellant to interact with the PEDW-administered appeal process.
+
+#### Current Scope
+
+- Section 78 (`S78`) appeal submission is implemented as the current MVP digital appeal flow.
+
+#### Long-Term Direction
+
+- the portal may be extended to support additional statutory planning appeal processes where PEDW chooses to offer digital submission support
+
+#### Business Meaning
+
+These are appeals made against decisions of a Local Planning Authority.
+
+In this capability, the portal is not just publishing information.
+
+It is providing a structured digital route through which an appellant can submit an appeal into the PEDW-administered process.
+
+---
+
+### 2. Statutory Public Information & Public Participation
+
+The portal also fulfils public-facing statutory information and participation responsibilities by consuming CRM-managed case information and exposing it through the portal.
+
+This includes:
+
+- publishing case information
+- publishing documents
+- displaying case progress
+- supporting public participation where legislation requires
+- exposing hearings, events, inquiries, or enquiries where applicable
+
+This capability applies across multiple statutory case types, not only digitally-submitted appeals.
+
+Representative examples include:
+
+- Planning Appeals
+- Developments of National Significance (`DNS`)
+- Significant Infrastructure Projects (`SIP`)
+- Harbour Revision Orders
+- Transport Act cases
+- Electricity Act cases
+
+#### Business Responsibility Split
+
+- CRM is the operational system of record used by PEDW to administer statutory planning casework.
+
+The portal consumes information from CRM and provides the public-facing statutory digital service, including case information, documents, participation opportunities and digital appeal services where supported.
+
+- the portal provides the public-facing statutory digital information service
+
+This means the portal often presents case information, progress, documents, and participation routes for statutory processes that are administered in CRM even where the portal is not the origin of the case submission.
+
+---
+
+## Business Terminology Glossary
+
+### Planning Appeal
+
+A planning appeal is a statutory challenge to a planning decision, usually a decision of a Local Planning Authority.
+
+In portal terms, an appeal may be:
+
+- digitally submitted through the portal, where that process is supported
+- or displayed/publicly surfaced as part of PEDW's statutory case-information responsibilities
+
+### Planning Application
+
+A planning application is the original application made to a Local Planning Authority for planning permission or related consent.
+
+It is not the same as an appeal.
+
+An appeal may arise later if the applicant disputes the authority's decision or non-determination.
+
+### Planning Case
+
+A planning case is the broader statutory case record being administered.
+
+Depending on case type, a case may represent:
+
+- an appeal
+- an application process such as DNS
+- another statutory planning or infrastructure process
+
+The portal presents case information across multiple such case families.
+
+### Statutory Case Type
+
+Every planning case belongs to a statutory case type defined by planning legislation.
+
+Examples include:
+
+- Planning Appeals
+- Developments of National Significance (DNS)
+- Significant Infrastructure Projects (SIP)
+- Harbour Revision Orders
+- Transport Act cases
+- Electricity Act cases
+
+Different statutory case types may expose different capabilities through the portal depending on legislative requirements.
+
+Examples include:
+
+- digital appeal services
+- public information
+- published documents
+- representations
+- hearings and events
+- case progress
+
+Not every statutory case type supports every portal capability.
+
+### Appellant
+
+The appellant is the party making an appeal against a Local Planning Authority decision.
+
+In many appeal flows, the appellant is the person or organisation submitting the appeal, either directly or through an agent.
+
+### Applicant
+
+The applicant is the party who made the original planning application.
+
+The applicant and appellant are sometimes the same party, but they are not conceptually identical terms.
+
+- applicant -> original application process
+- appellant -> subsequent appeal process
+
+### Representation
+
+A representation is a formal comment, statement, or submission made by a participant in response to a planning case where public participation is allowed or required.
+
+Representations are part of statutory participation and public-facing case handling, not just appeal submission.
+
+### Local Planning Authority (LPA)
+
+The Local Planning Authority is the authority that made the original planning decision or is otherwise responsible at local level for the planning matter.
+
+The portal uses `LPA` widely because many appeals and planning processes are defined in relation to LPA decisions or LPA participation.
+
+### DNS
+
+`DNS` means **Developments of National Significance**.
+
+These are nationally significant planning applications handled under a distinct statutory route.
+
+The portal supports public-facing statutory information and participation for DNS cases.
+
+### SIP
+
+`SIP` means **Significant Infrastructure Projects**.
+
+These are large infrastructure-related statutory case types administered through PEDW/CRM and surfaced through the portal where relevant.
+
+### CRM
+
+`CRM` refers to the Microsoft Dynamics 365 / Dataverse system that acts as the operational system of record for PEDW case administration.
+
+In portal terms, CRM typically owns:
+
+- case records
+- statutory status/progress information
+- case relationships
+- published document metadata
+- participation-related data
+
+### PEDW
+
+`PEDW` means **Planning and Environment Decisions Wales**.
+
+PEDW administers statutory planning and related casework in Wales.
+
+The portal is the public-facing digital service layer supporting PEDW responsibilities.
+
+---
+
+## Relationship Between Concepts
+
+The following simplified relationships are useful for understanding the portal:
+
+```text
+Planning Application
+        │
+        ▼
+Local Planning Authority decision
+        │
+        ▼
+Possible Planning Appeal
+        │
+        ▼
+PEDW statutory case administration (CRM)
+        │
+        ▼
+Portal
+    ├── Digital appeal services (where supported)
+    ├── Public case information
+    ├── Published documents
+    ├── Case progress
+    ├── Public participation
+    └── Hearings / events where applicable
+```
+
+Not all portal cases begin as digital appeals.
+
+Some begin as other statutory planning or infrastructure case types that PEDW administers and the portal then publishes and supports publicly.
+
+---
+
+## Guiding Principle
+
+The portal does not attempt to make every statutory planning process behave identically.
+
+Planning legislation defines different statutory processes with different participation models, submission requirements, documentation requirements and publication obligations.
+
+The portal therefore provides a common digital platform while allowing individual statutory case types to expose only the capabilities required by their legislation.
+
+Shared platform services maximise reuse without attempting to normalise legislative differences.
+
+---
+
+## Relationship to Architecture
+
+This document explains the business domain and terminology only.
+
+It does not define:
+
+- architectural classification
+- implementation workstreams
+- technical boundaries
+- service or route ownership
+
+Those are defined in the architecture and programme documents.
+
+This document exists so future architectural and implementation work uses correct planning-domain terminology and does not assume that all portal capabilities are only about appeals.

context/implementation-governance.md

@@ -0,0 +1,391 @@
+# Implementation Governance
+
+## Status
+
+Governance only.
+
+This document defines how future PEDW maintainability and adoption implementation slices should be planned, branched, executed, validated, documented, and reported.
+
+It is a delivery-governance companion to:
+
+- `GUARDRAILS.md` — platform safety and regression prevention
+- `context/maintainability-adoption-programme.md` — maintainability workstreams and relative priority
+- `context/architecture.md` — current architectural state and programme phase
+
+It does **not** reopen architecture discovery.
+
+It does **not** authorize broad refactor by default.
+
+---
+
+## Required Context Read
+
+The following files were read before drafting this governance document:
+
+- `GUARDRAILS.md`
+- `context/maintainability-adoption-programme.md`
+- `context/architecture.md`
+- `context/api-grouping-adoption-roadmap.md`
+- `context/remaining-architecture-candidates.md`
+- `memory-bank/change-log.md`
+- `memory-bank/open-questions.md`
+
+These were used as the evidence base for the current programme stage and implementation discipline.
+
+---
+
+## 1. Current Programme Stage
+
+The current PEDW programme stage should be understood as follows:
+
+- broad architecture discovery is complete
+- business-policy discovery is complete
+- API grouping rollout has reached a natural boundary for read-style façade slices
+- maintainability work is now implementation-led
+- future work should proceed through small, behaviour-preserving adoption slices
+
+This means future implementation should be framed as:
+
+- bounded adoption
+- extraction planning
+- compatibility-preserving consolidation
+- validation-led execution
+
+and **not** as:
+
+- renewed broad discovery
+- speculative redesign
+- large structural migration
+
+---
+
+## 2. Implementation Slice Definition
+
+An implementation slice should be defined as:
+
+- one branch
+- one logical change set
+- one maintainability workstream
+- one bounded adoption target
+- behaviour-preserving unless explicitly approved otherwise
+
+### Accepted Maintainability Workstreams
+
+Future slices should belong to one of the established workstreams:
+
+- Domain Layer Adoption
+- CRM Display Infrastructure
+- Navigation Infrastructure
+- API Journey Grouping
+
+### Slice Boundary Rule
+
+A slice should not mix unrelated workstreams unless:
+
+- the relationship is already proven
+- the implementation boundary is still small
+- the validation burden remains tractable
+
+If that cannot be shown clearly, split the work.
+
+---
+
+## 3. Required Slice Lifecycle
+
+Every implementation slice should follow this lifecycle:
+
+1. **Characterize**
+2. **Validate**
+3. **Extract / Add**
+4. **Adopt**
+
+### 1. Characterize
+
+Identify the existing behaviour that must be preserved.
+
+This may be lightweight when the seam is already well-proven, but it must still be explicit for each new adoption surface.
+
+At minimum, characterization should clarify:
+
+- what the current behaviour is
+- where the active consumers are
+- what fallbacks/contracts must remain stable
+- what adjacent areas are intentionally excluded
+
+### 2. Validate
+
+Confirm that the proposed seam is safe to adopt.
+
+Validation at this stage means proving that:
+
+- the boundary is already characterized well enough
+- the slice is small enough to review safely
+- regression risk is understood
+
+### 3. Extract / Add
+
+Introduce the smallest viable helper, compatibility layer, façade, or reusable abstraction needed for the slice.
+
+Prefer:
+
+- additive helpers
+- delegation wrappers
+- small pure functions
+- compatibility-preserving abstractions
+
+over replacement or broad rewrite.
+
+### 4. Adopt
+
+Adopt the extracted seam in one bounded target area.
+
+The adoption target should be explicit, such as:
+
+- one consumer family
+- one route family
+- one page cluster
+- one service/helper cluster
+
+Do not attempt mass adoption by default.
+
+---
+
+## 4. Branching Governance
+
+All future implementation slices should follow these branching rules:
+
+- always start from latest `origin/SIPS-Development`
+- never work directly on:
+    - `SIPS-Development`
+    - `main`
+    - `master`
+- use a dedicated branch:
+    - `feature/<short-description>`
+    - or `TASK<id>-<short-description>`
+- one logical change set per branch
+- keep unrelated local files uncommitted
+- do not commit `.env.local`
+- commit only after focused validation passes
+- final report must include commit hash
+
+### Branch Discipline
+
+One branch should correspond to one reviewable slice.
+
+If the work expands into multiple unrelated changes, stop and split the work instead of continuing on one branch.
+
+---
+
+## 5. Prompt Governance
+
+Future implementation prompts should include:
+
+- Objective
+- Required Context
+- Scope
+- Out of Scope
+- Constraints
+- Tests
+- Validation
+- Documentation
+- Expected Response Format
+
+### Prompt Requirements
+
+Every implementation prompt should explicitly state:
+
+- which maintainability workstream the slice belongs to
+- which documents must be read
+- which files/routes/components are in scope
+- which adjacent areas are excluded
+- what behaviour must be preserved
+
+This is required so implementation remains bounded and auditable.
+
+---
+
+## 6. Behaviour Preservation Rules
+
+By default, preserve:
+
+- runtime behaviour
+- API contracts
+- payload shapes
+- query parameter names
+- status codes
+- CRM queries
+- Azure Storage behaviour
+- queue behaviour
+- GOV.UK Notify behaviour
+- auth/session behaviour
+- relay hash behaviour
+- EN/CY parity
+- accessibility expectations
+
+If a slice needs to alter any of the above, that must be explicitly authorized in the prompt and then called out clearly in planning, validation, and final reporting.
+
+### Business Capability Clarification
+
+Implementation slices should recognise the distinction between:
+
+- digital appeal submission capabilities
+- statutory public information capabilities
+
+Shared platform improvements may support both, but future slices should not assume that these capabilities always have identical workflows, actors, or statutory responsibilities.
+
+---
+
+## 7. Prohibited by Default
+
+The following are prohibited by default unless explicitly approved:
+
+- broad refactors
+- rewrites
+- replacements
+- redesigns
+- modernization for its own sake
+- route deletion
+- route movement
+- API renaming
+- folder restructuring
+- CRM redesign
+- broad test rewrites
+- unrelated cleanup
+
+### Interpretation
+
+This governance model is designed to protect a live, compatibility-sensitive system.
+
+The default assumption is always:
+
+> preserve behaviour, reduce risk, and keep the slice small.
+
+---
+
+## 8. Test and Validation Expectations
+
+Validation should be scoped to the slice.
+
+Preferred validation forms include:
+
+- focused characterization tests
+- helper/unit tests for extracted logic
+- route contract tests for API changes
+- EN/CY checks for user-facing output
+- manual smoke notes for sensitive flows where appropriate
+
+### Validation Rule
+
+Avoid requiring full repository validation unless the slice clearly justifies it.
+
+Future slices should prefer:
+
+- narrow targeted validation
+- proof of behaviour preservation at the changed seam
+- proportionate coverage for risk-sensitive areas
+
+### Sensitive Flow Reminder
+
+For auth, storage, queue, notification, or high-risk routing changes, validation should also reflect the additional guardrails already recorded in `GUARDRAILS.md` and related operational docs.
+
+---
+
+## 9. Documentation Expectations
+
+Every non-trivial implementation slice should update:
+
+- `memory-bank/change-log.md`
+
+If already present, also update:
+
+- `memory-bank/maintainability-tracker.md`
+
+### Architecture / Context Update Rule
+
+Only update architecture or context documents when:
+
+- the slice changes the implementation state of a workstream
+- the slice proves or invalidates an architectural assumption
+- the slice completes a planned adoption milestone
+
+Do not update architecture/context docs for routine implementation churn unless one of those conditions is true.
+
+---
+
+## 10. Expected Final Response Format
+
+For future implementation slices, final reporting should include:
+
+- Branch
+- Commit
+- Files Added
+- Files Modified
+- Audit / Characterization Findings
+- Implementation Summary
+- Behaviour Preservation Notes
+- Tests / Validation Performed
+- Documentation Updated
+- Risks / Cautions
+- Completion Status
+- Recommendation / Next Slice
+
+### Reporting Rule
+
+The final report should make it easy to answer:
+
+- what was changed
+- what was preserved
+- how it was validated
+- what remains for the next slice
+
+---
+
+## Relationship to Existing Governance and Planning Documents
+
+### `GUARDRAILS.md`
+
+`GUARDRAILS.md` defines platform safety and regression prevention rules.
+
+This document does **not** replace those guardrails.
+
+It defines the execution model for future implementation slices.
+
+### `context/maintainability-adoption-programme.md`
+
+The maintainability programme defines **what** workstreams should be advanced.
+
+This document defines **how** each implementation slice should be executed.
+
+### `context/architecture.md`
+
+The architecture reference defines the current system and programme phase.
+
+This document translates that programme phase into practical implementation governance.
+
+---
+
+## Programme Governance Recommendation
+
+Future PEDW implementation work should proceed as:
+
+```text
+one workstream
+    ↓
+one bounded slice
+    ↓
+characterize
+    ↓
+validate
+    ↓
+extract/add
+    ↓
+adopt
+    ↓
+focused validation
+    ↓
+document and report
+```
+
+The default operating rule remains:
+
+> small, explicit, behaviour-preserving implementation slices only.

context/maintainability-adoption-programme.md

@@ -0,0 +1,488 @@
+# Maintainability Adoption Programme
+
+## Status
+
+Planning only.
+
+Architecture discovery is complete.
+
+Business-policy discovery is complete.
+
+The remaining work is implementation-led, and future improvements should be delivered as **small, incremental, behaviour-preserving adoption slices** rather than as new discovery streams.
+
+This document provides the implementation roadmap that emerges naturally from the completed architecture programme.
+
+The programme exists to improve the shared platform supporting:
+
+- existing statutory public information capabilities
+- current digital appeal submission
+- future supported digital appeal submission processes
+- future legislative and case-type enhancements where PEDW extends portal support
+
+It is a planning document only.
+
+It does **not** recommend large-scale rewrite, redesign, route replacement, framework migration, CRM redesign, or broad modernization.
+
+---
+
+## Required Context Read
+
+The following files were read before drafting this programme:
+
+- `context/architecture.md`
+- `context/portal-api-platform-assessment.md`
+- `context/api-grouping-adoption-roadmap.md`
+- `context/remaining-architecture-candidates.md`
+- `memory-bank/change-log.md`
+
+Additional evidence used from completed characterization work:
+
+- Bilingual CRM Display Resolution Audit
+- Bilingual Navigation & Link Resolution Audit
+
+These were treated as completed evidence inputs rather than reopened as new discovery exercises.
+
+---
+
+## Programme Status
+
+### Discovery Programme Position
+
+The PEDW architecture programme should now be understood as having completed its main discovery and characterization work.
+
+Current state:
+
+- architecture discovery: complete
+- business-policy discovery: complete
+- principal policy candidates: established
+- principal presentation and compatibility candidates: characterized
+- remaining work: adoption planning, extraction sequencing, bounded implementation slices, and validation-led runtime adoption
+
+This means future work should no longer be framed as:
+
+- broad discovery
+- open-ended architecture hunting
+- large speculative redesign
+
+It should instead be framed as:
+
+- characterization-backed implementation planning
+- incremental helper extraction where justified
+- selective runtime adoption of already-proven seams
+- maintainability improvements that preserve current behaviour
+
+---
+
+## Maintainability Principles
+
+The maintainability programme should follow this sequence:
+
+1. **Characterize**
+2. **Validate**
+3. **Extract / Add**
+4. **Adopt**
+
+### Interpretation
+
+#### Characterize
+
+Understand the existing behaviour first.
+
+Capture repeated patterns, implementation differences, fallbacks, risks, and current ownership before introducing a shared abstraction.
+
+#### Validate
+
+Confirm that the proposed seam is real, that behaviour is stable enough to preserve, and that the slice boundary is safe.
+
+#### Extract / Add
+
+Prefer small compatibility helpers or additive abstractions over replacement.
+
+#### Adopt
+
+Adopt new abstractions incrementally in bounded vertical slices.
+
+Do not attempt broad retrospective migration in one change.
+
+### Programme Prohibitions
+
+Future maintainability work should **not** default to:
+
+- rewrite
+- replace
+- redesign
+- modernize
+
+without explicit approval.
+
+These approaches carry materially higher regression risk and do not match the refactor branch discipline.
+
+---
+
+## Workstream Classification
+
+The maintainability programme now naturally groups into a small number of implementation workstreams.
+
+Each workstream below reflects already-characterized architecture boundaries or compatibility seams.
+
+---
+
+### 1. Domain Layer Adoption
+
+#### Objective
+
+Increase runtime adoption of already-proven domain and policy seams without expanding them into a broader unproven domain model.
+
+#### Architectural Classification
+
+- Business Decision Model
+- narrow domain-layer adoption
+
+#### Representative Areas
+
+- Appeal Type Policy
+- Representation Entry Policy
+- Representation Type Availability
+
+#### Current Maturity
+
+- extraction substantially complete
+- characterization confidence high
+- runtime adoption still selective and uneven across consumers
+
+#### Implementation Strategy
+
+- preserve the current intentionally narrow domain-layer scope
+- favour consumer-by-consumer runtime adoption
+- avoid converting surrounding compatibility or presentation code into faux domain logic
+- protect behaviour with bounded characterization and targeted validation when new adoption slices occur
+
+#### Expected Maintenance Benefit
+
+- clearer ownership for true business-rule logic
+- less repeated policy branching in UI/loaders/routes
+- safer future changes in policy-sensitive areas
+
+---
+
+### 2. CRM Display Infrastructure
+
+#### Objective
+
+Create a clearer single source of truth for CRM-driven bilingual display behaviour while preserving current runtime output.
+
+#### Architectural Classification
+
+- CRM Compatibility Model
+- Presentation Infrastructure
+
+#### Representative Areas
+
+- CRM formatted values
+- lookup translation
+- JSONPath-based translation access
+- picklists
+- status labels
+- stage labels
+- appeal type labels
+- specialist process labels
+- LPA display
+
+#### Current Maturity
+
+- characterized
+- repeated dominant pattern identified
+- several partial abstractions already present
+- suitable for incremental implementation
+
+#### Implementation Strategy
+
+- start from the dominant existing compatibility pattern rather than designing a new model from scratch
+- prefer additive shared resolvers over broad replacement
+- adopt first in bounded, read-only display families
+- preserve current fallback behaviour per consumer unless an explicit standardization decision is approved
+
+#### Expected Maintenance Benefit
+
+- reduced duplication of display-resolution logic
+- improved EN/CY consistency
+- improved maintainability of CRM-driven presentation surfaces
+- lower risk of display drift across search, case, admin, my portal, and PDF consumers
+
+---
+
+### 3. Navigation Infrastructure
+
+#### Objective
+
+Establish a clearer single source of truth for bilingual navigation behaviour across public, my portal, auth, and case-navigation journeys.
+
+#### Architectural Classification
+
+- Routing / Navigation Infrastructure
+- Presentation / i18n Infrastructure
+
+#### Representative Areas
+
+- route resolution
+- locale-aware links
+- breadcrumbs
+- callback URLs
+- redirects
+- search/case navigation
+- my portal/public navigation
+- bilingual back-link and step-back behaviour
+
+#### Current Maturity
+
+- characterized
+- repeated locale-switching and route-construction logic identified
+- partial routing helper seams already exist
+- recommended for incremental implementation
+
+#### Implementation Strategy
+
+- extend the newer routing-helper seam rather than adding a competing navigation model
+- adopt one journey family at a time
+- keep internal-route resolution separate from CRM display resolution
+- treat auth callback/redirect handling as compatibility-sensitive and adopt cautiously
+
+#### Expected Maintenance Benefit
+
+- less duplicated Welsh/English route selection
+- clearer route ownership and query preservation rules
+- reduced EN/CY navigation drift
+- safer future route additions and journey updates
+
+---
+
+### 4. API Journey Grouping
+
+#### Objective
+
+Continue the additive grouping approach only where it is already proven to be low-risk and maintainable.
+
+#### Architectural Classification
+
+- API Platform Maintainability
+- Route Ownership / Journey Grouping
+
+#### Current Maturity
+
+- planning and pilot work substantially proven
+- bounded adoption slices completed for selected read families
+- the read-style rollout has reached its natural boundary
+
+#### Implementation Strategy
+
+- continue using grouped routes for new bounded APIs where ownership is clear
+- prefer additive façade grouping for new read-oriented journey families
+- keep existing canonical handlers stable behind the façade where appropriate
+- avoid broad retrospective rollout into workflow/orchestration-heavy areas
+
+#### Boundary Guidance
+
+Do not treat this workstream as permission to:
+
+- reorganize all historical APIs
+- group orchestration-heavy families using the same pattern
+- migrate contract-critical routes in bulk
+
+#### Expected Maintenance Benefit
+
+- improved findability
+- clearer journey ownership
+- safer future route placement
+- better consistency in newer API work without destabilising established orchestration families
+
+---
+
+## Relative Priority
+
+The recommended implementation priority order is:
+
+1. **Domain Layer Adoption**
+2. **CRM Display Infrastructure**
+3. **Navigation Infrastructure**
+4. **API Journey Grouping**
+
+### Priority Rationale
+
+#### 1. Domain Layer Adoption
+
+This has the strongest established business-value boundary and the clearest policy ownership.
+
+The architecture programme already proved these seams, so the remaining work is mainly controlled runtime adoption.
+
+#### 2. CRM Display Infrastructure
+
+This area shows high duplication with one dominant repeated pattern and already-characterized opportunities for shared compatibility helpers.
+
+It offers a strong maintainability return without requiring business-rule change.
+
+#### 3. Navigation Infrastructure
+
+This area is also strongly justified, but the implementation landscape is more mixed because it spans:
+
+- internal routes
+- breadcrumbs
+- auth callbacks
+- redirects
+- public/myportal variants
+- external bilingual links
+
+That makes it slightly broader than CRM display infrastructure and therefore better positioned after CRM display adoption begins.
+
+#### 4. API Journey Grouping
+
+This remains valuable, but the roadmap already shows that the current additive read-style rollout has reached a natural stop point.
+
+This workstream should continue selectively, especially for new bounded read families, but should not dominate the programme at the expense of higher-value shared maintainability seams.
+
+---
+
+## Guiding Principles
+
+Future maintainability work should favour:
+
+- single source of truth
+- reusable abstractions
+- behaviour preservation
+- incremental adoption
+- characterization-first implementation
+- bounded vertical slices
+- additive compatibility helpers over replacement
+- explicit validation evidence for sensitive flows
+
+Where multiple implementations already coexist, the programme should prefer:
+
+- proving the dominant pattern
+- extracting the smallest safe shared seam
+- adopting it in one narrow consumer family first
+
+rather than imposing a large harmonization effort in one change.
+
+---
+
+## Explicit Non-Goals
+
+This programme is **not** attempting:
+
+- Domain-Driven Design conversion
+- framework migration
+- large-scale rewrites
+- folder restructuring
+- API replacement
+- CRM redesign
+- broad route migration
+- aesthetic modernization for its own sake
+
+It is a maintainability adoption programme, not a transformation programme.
+
+---
+
+## Adoption Model
+
+The intended shape of future work is:
+
+```text
+characterized boundary
+    ↓
+small helper / façade / compatibility seam
+    ↓
+bounded consumer adoption
+    ↓
+validation
+    ↓
+repeat only where evidence justifies it
+```
+
+This should apply across:
+
+- domain-layer adoption
+- CRM display infrastructure
+- navigation infrastructure
+- API grouping
+
+---
+
+## Relationship to Existing Architecture
+
+This document does not replace the existing architecture records.
+
+It sits on top of them as the implementation roadmap for the next phase.
+
+Relationship summary:
+
+- `context/architecture.md`
+    - defines the programme phase as adoption planning
+- `context/portal-api-platform-assessment.md`
+    - establishes API maintainability problems as findability, ownership clarity, consistency, and reuse discipline
+- `context/api-grouping-adoption-roadmap.md`
+    - provides the bounded guidance for additive API grouping and its natural boundary
+- `context/remaining-architecture-candidates.md`
+    - confirms discovery is complete and remaining work is adoption-planning, characterization coverage, extraction planning, and adoption
+- completed bilingual audits
+    - provide evidence that CRM display infrastructure and navigation infrastructure are now justified maintainability workstreams
+
+---
+
+## Recommended Next Planning / Implementation Discipline
+
+When future slices are proposed, each should state:
+
+- the workstream it belongs to
+- the characterized seam being adopted
+- the smallest bounded consumer scope
+- the preserved behaviour constraints
+- the validation evidence required
+
+Preferred slice types:
+
+- one helper extraction
+- one consumer-family adoption
+- one compatibility seam formalization
+- one bounded API grouping façade adoption
+
+Avoid mixed multi-workstream slices unless the relationship is already proven and the risk is low.
+
+---
+
+## Programme Recommendation
+
+PEDW should now treat maintainability improvement as a **planned adoption programme** rather than as a continuing discovery exercise.
+
+The highest-value future work is likely to come from:
+
+1. continued narrow domain-layer adoption
+2. incremental CRM display infrastructure adoption
+3. incremental navigation infrastructure adoption
+4. selective continuation of additive API grouping where the route family is bounded and non-orchestration-heavy
+
+The overall rule remains:
+
+> preserve behaviour, improve clarity, and adopt small reusable seams incrementally.
+
+---
+
+## Relationship to Implementation Governance
+
+This document defines **what** maintainability workstreams should be advanced and in what relative order.
+
+The standard execution model for future implementation slices is recorded separately in:
+
+- `context/implementation-governance.md`
+
+That governance document defines **how** each future slice should be:
+
+- planned
+- branched
+- executed
+- validated
+- documented
+- reported
+
+The maintainability programme and implementation governance documents should therefore be read together:
+
+- maintainability adoption programme -> **what to advance**
+- implementation governance -> **how to execute each slice safely**

memory-bank/change-log.md

@@ -18,6 +18,191 @@ Follow-ups:
 
 ---
 
+### CL-2026-06-29-BUSINESS-DOMAIN-OVERVIEW: clarify PEDW planning-domain terminology and portal business responsibilities
+
+date: 2026-06-29
+author: Cline
+scope: `context/business-domain-overview.md`, `context/architecture.md`, `context/maintainability-adoption-programme.md`, `context/implementation-governance.md`, `memory-bank/change-log.md`
+type: change
+rationale: Add a concise business-domain overview so future architectural and implementation work uses correct PEDW planning terminology and clearly distinguishes between digital appeal submission responsibilities and broader statutory public information/public participation responsibilities.
+impact: Documentation/context only; clarifies business-domain terminology, portal business capabilities, and the relationship between statutory process administration in CRM/PEDW and the portal's public-facing role. No runtime, API, auth/session, CRM, storage, queue, notification, routing, i18n, or behaviour change.
+status: completed
+
+Summary:
+
+- Confirmed the required business-domain clarification context was read before drafting:
+    - `context/architecture.md`
+    - `context/maintainability-adoption-programme.md`
+    - `context/implementation-governance.md`
+    - `GUARDRAILS.md`
+    - `memory-bank/change-log.md`
+- Created new business-domain clarification document:
+    - `context/business-domain-overview.md`
+- Recorded the portal's two principal business capabilities as:
+    - Digital Appeal Submission
+    - Statutory Public Information & Public Participation
+- Clarified that:
+    - digital appeal submission currently applies to supported appeal processes only (currently S78 MVP)
+    - the portal also fulfils statutory public-facing information and participation responsibilities across multiple PEDW-administered case types
+    - CRM / PEDW administers the statutory process
+    - the portal provides the public-facing statutory digital service layer
+- Added a concise business glossary covering key planning-domain terms including:
+    - Planning Appeal
+    - Planning Application
+    - Planning Case
+    - Appellant
+    - Applicant
+    - Representation
+    - Local Planning Authority (LPA)
+    - DNS
+    - SIP
+    - CRM
+    - PEDW
+- Updated `context/architecture.md` with a short business-capability context section without altering established architectural classifications.
+- Updated `context/maintainability-adoption-programme.md` so the programme purpose clearly reflects support for both statutory public information capabilities and current/future supported digital appeal submission capabilities.
+- Updated `context/implementation-governance.md` with a short clarification that implementation slices should recognise the distinction between digital appeal submission capabilities and statutory public information capabilities.
+- Left `GUARDRAILS.md` unchanged because no contradiction was identified and no guardrail meaning needed alteration.
+
+Validation:
+
+- Documentation-only clarification slice.
+- No application code or tests changed.
+- Intended diff-format validation for this slice:
+    - `git diff --check -- context/business-domain-overview.md context/architecture.md context/maintainability-adoption-programme.md context/implementation-governance.md memory-bank/change-log.md`
+
+Follow-ups:
+
+- Use `context/business-domain-overview.md` as the business terminology baseline for future architecture and implementation prompts where planning-domain terminology may otherwise be ambiguous.
+- Keep future workstream and implementation language aligned with the distinction between appeal submission and broader statutory public information responsibilities.
+
+---
+
+### CL-2026-06-29-IMPLEMENTATION-GOVERNANCE: create standard execution governance for future maintainability slices
+
+date: 2026-06-29
+author: Cline
+scope: `context/implementation-governance.md`, `context/maintainability-adoption-programme.md`, `GUARDRAILS.md`, `memory-bank/change-log.md`
+type: change
+rationale: Create a dedicated governance document defining how future PEDW implementation slices should be planned, branched, executed, validated, documented, and reported, and add minimal linked references so the current programme stage and execution model are clear without reopening discovery.
+impact: Documentation/context only; defines implementation-slice governance for future maintainability/adoption work, clarifies the relationship between guardrails, architecture phase, and maintainability roadmap, and adds linked references in existing docs. No runtime, API, auth/session, CRM, storage, queue, notification, routing, i18n, or behaviour change.
+status: completed
+
+Summary:
+
+- Confirmed the required governance context was read before drafting:
+    - `GUARDRAILS.md`
+    - `context/maintainability-adoption-programme.md`
+    - `context/architecture.md`
+    - `context/api-grouping-adoption-roadmap.md`
+    - `context/remaining-architecture-candidates.md`
+    - `memory-bank/change-log.md`
+    - `memory-bank/open-questions.md`
+- Created new governance document:
+    - `context/implementation-governance.md`
+- Recorded the current programme stage as:
+    - broad architecture discovery complete
+    - business-policy discovery complete
+    - API grouping rollout at a natural boundary for read-style façade slices
+    - maintainability work now implementation-led
+    - future work to proceed through small, behaviour-preserving adoption slices
+- Defined the standard implementation-slice model as:
+    - one branch
+    - one logical change set
+    - one maintainability workstream
+    - one bounded adoption target
+    - behaviour-preserving unless explicitly approved otherwise
+- Recorded the required slice lifecycle:
+    - characterize
+    - validate
+    - extract/add
+    - adopt
+- Recorded branching governance, prompt governance, behaviour-preservation defaults, prohibited-by-default changes, scoped validation expectations, documentation expectations, and required final reporting format.
+- Updated `context/maintainability-adoption-programme.md` with a short section clarifying that the maintainability programme defines **what** to advance, while implementation governance defines **how** future slices should be executed.
+- Updated `GUARDRAILS.md` Related Docs with minimal references to:
+    - `context/implementation-governance.md`
+    - `context/maintainability-adoption-programme.md`
+- Did not update `memory-bank/open-questions.md` because no new unresolved governance question was created by this slice.
+- Did not create `memory-bank/maintainability-tracker.md` because it does not already exist and was not clearly established as current project convention for this slice.
+
+Validation:
+
+- Documentation-only governance slice.
+- No application code or tests changed.
+- Intended diff-format validation for this slice:
+    - `git diff --check -- context/implementation-governance.md context/maintainability-adoption-programme.md GUARDRAILS.md memory-bank/change-log.md`
+
+Follow-ups:
+
+- Use `context/implementation-governance.md` as the default execution model for future maintainability/adoption implementation prompts.
+- Keep future slice prompts explicit about workstream, bounded scope, preservation rules, and validation expectations.
+
+---
+
+### CL-2026-06-29-MAINTAINABILITY-ADOPTION-PROGRAMME: create architecture roadmap for incremental maintainability implementation workstreams
+
+date: 2026-06-29
+author: Cline
+scope: `context/maintainability-adoption-programme.md`, `memory-bank/change-log.md`
+type: change
+rationale: Consolidate the maintainability implementation workstreams that naturally emerged from the completed architecture discovery programme into one planning document so future work can proceed through bounded, behaviour-preserving adoption slices rather than reopening discovery.
+impact: Documentation/context only; records programme status, maintainability principles, workstream classification, relative priorities, and non-goals for future implementation planning. No runtime, routing, auth/session, CRM, storage, queue, notification, i18n, or behaviour change.
+status: completed
+
+Summary:
+
+- Confirmed the required context was read before drafting the programme document:
+    - `context/architecture.md`
+    - `context/portal-api-platform-assessment.md`
+    - `context/api-grouping-adoption-roadmap.md`
+    - `context/remaining-architecture-candidates.md`
+    - `memory-bank/change-log.md`
+- Used the completed Bilingual CRM Display Resolution Audit and Bilingual Navigation & Link Resolution Audit as evidence inputs rather than reopening those discovery slices.
+- Created new planning document:
+    - `context/maintainability-adoption-programme.md`
+- Recorded the programme position that:
+    - architecture discovery is complete
+    - business-policy discovery is complete
+    - remaining work is implementation-led
+    - future improvements should be incremental and behaviour-preserving
+- Recorded maintainability principles:
+    - characterize
+    - validate
+    - extract/add
+    - adopt
+    - and explicit prohibitions against rewrite/replace/redesign/modernize without approval
+- Classified the main maintainability workstreams:
+    - domain layer adoption
+    - CRM display infrastructure
+    - navigation infrastructure
+    - API journey grouping
+- Recorded for each workstream:
+    - objective
+    - architectural classification
+    - current maturity
+    - implementation strategy
+    - expected maintenance benefit
+- Recommended relative implementation priority order:
+    1. domain layer adoption
+    2. CRM display infrastructure
+    3. navigation infrastructure
+    4. API journey grouping
+- Recorded programme-wide guiding principles, explicit non-goals, and the expected adoption model for future bounded slices.
+
+Validation:
+
+- Documentation-only planning slice.
+- Checked consistency against the current architecture phase (`Adoption Planning`), established policy boundaries, API grouping boundary guidance, and completed characterization outputs.
+- No code, route, contract, or runtime changes performed.
+- Intended lightweight validation for this slice:
+    - `git diff --check`
+
+Follow-ups:
+
+- Use this document as the top-level roadmap when proposing future maintainability implementation slices.
+- Keep future workstream proposals bounded to one characterized seam and one adoption surface where possible.
+
+---
+
 ### CL-2026-06-25-WORKFLOW-ORCHESTRATION-DOC-VALIDATION: validate whether existing architecture docs already cover PEDW workflow/orchestration
 
 date: 2026-06-25