413 lines
10 KiB
Markdown
413 lines
10 KiB
Markdown
# 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/<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.
|