# 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. ### CRM Display Infrastructure Rule When rendering a standard CRM formatted/display value: - `resolveCrmDisplayValue(...)` should be used. Developers should not introduce new inline JSONPath lookups for the standard CRM formatted/display-value translation pattern. If the translation concern does not match the helper boundary, it should be treated as a separate abstraction rather than extending the helper. This includes concerns such as: - keyed lookup translation - list translation - hyperlink / website rendering - mixed presentation rows - lifecycle interpretation - status interpretation - post-decision interpretation - other derived presentation values --- ## 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/` - or `TASK-` - 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.