Robert Bond
@@ -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.
|
||||
Reference in New Issue
Block a user