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.

---

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:

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.