pedwfrontend/context/implementation-governance.md

# 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.