diff --git a/context/current-platform-state.md b/context/current-platform-state.md index a14086ce..f9223de4 100644 --- a/context/current-platform-state.md +++ b/context/current-platform-state.md @@ -15,6 +15,11 @@ PEDW is in a **late-stage refactor stabilization** phase. - New Appeal slice stream documented complete (`context/refactor-tracker.md`, `context/newappeal-refactor-current-state.md`). - Significant route/breadcrumb decomposition and helper extraction completed. - Broad endpoint contract hardening completed across key clusters. +- Representation Participation Availability investigation completed from a technical discovery/documentation perspective. +- Representation participation behaviour is now documented as one coherent decision model with layered appeal-type, specialist-process, participant-type, consultation, and date-window exceptions. +- Source documents added: + - `docs/representation-participation-availability.md` (developers / architects / maintainers) + - `docs/representation-participation-business-review.md` (business / product / SME validation) ## What is incomplete @@ -22,6 +27,7 @@ PEDW is in a **late-stage refactor stabilization** phase. - SSR loader resilience normalization across myportal/representation/new appeal. - Logging hardening consistency in auth/file/account-sensitive paths. - Remaining decomposition hotspots (`components/elements/index.js`, representation flow internals). +- Business validation of Representation Participation Availability before any further representation-policy adoption, expansion, or behaviour-change work. ## Operational risk profile (current) @@ -36,3 +42,17 @@ Top active risks: - Some context docs still describe pre-refactor representation baseline; treat those as historical unless updated by active slice evidence. - Legacy commented code remains in active files (especially journey files) and should be treated as cleanup debt, not source-of-truth runtime behaviour. + +## Representation Participation Availability — Current State + +- Technical discovery/documentation stream is complete. +- Current architectural conclusion: do **not** continue searching for a new representation domain boundary at this point. +- Representation participation is best understood as one coherent decision model with layered exceptions rather than a set of unrelated CTA rules. +- Known divergences and compatibility-sensitive behaviours are documented and should be preserved unless an explicit business decision authorizes change. +- Current state: awaiting business validation of `docs/representation-participation-business-review.md` before any further representation-policy adoption, expansion, or behavioural change work. + +## Next likely discovery candidate + +- **Case Lifecycle / Status Decision Model Discovery** + - Investigate how the portal interprets case progress, stages, statuses, closed states, dashboard grouping, and user-facing lifecycle messaging. + - Treat this as discovery only until the new representation participation documentation has been reviewed and business validation feedback is available. diff --git a/docs/representation-participation-availability.md b/docs/representation-participation-availability.md new file mode 100644 index 00000000..91d5ae82 --- /dev/null +++ b/docs/representation-participation-availability.md @@ -0,0 +1,593 @@ +# Representation Participation Availability + +## Purpose + +This document records the current live **Representation Participation Availability** model used by the PEDW portal. + +It is intended to preserve knowledge established through characterization and discovery work so that future developers, architects, and maintainers do not need to repeat the same investigations. + +This document is based on observed current behaviour across the live decision paths, including: + +- `lib/domain/representation-policy/*` +- `components/case/summary/utils/representationEntry.js` +- `components/search/repsonresults.js` +- existing characterization documentation and tests + +This is a **behaviour characterization document**, not a redesign proposal. + +--- + +## Executive Summary + +Current portal behaviour appears to be making one broad business decision: + +> Can this participant engage in representation or consultation activity for this case right now? + +The current system does not behave like a set of unrelated button rules. + +Instead, it behaves like a broadly coherent participation-availability policy with layered exceptions based on: + +- appeal type +- specialist process +- participant type +- date-window state +- consultation state +- CRM field availability/variants + +The policy has evolved organically over time. + +As a result, some behaviours are clearly structured and repeatable, while others are compatibility-sensitive and exception-driven. A small number of current divergences between consumers appear historical rather than explicitly modelled, but they are now characterized and must be treated as preserved live behaviour unless a deliberate business change is approved. + +--- + +## Core Business Decision + +The decision being made is: + +> Can this participant engage in representation or consultation activity for this case right now? + +This is broader than a simple CTA visibility question. + +In practice, the live system decides a combination of: + +- whether participation is available at all +- whether the relevant participation window is open +- whether an exception applies for the case/process/participant combination +- whether unavailable-state messaging should be shown, suppressed, or rendered differently +- whether the case is currently handled as a consultation rather than a representation + +This means the model should be understood as a **participation-availability decision**, not merely a rendering decision. + +--- + +## Decision Inputs + +The following inputs have been confirmed to affect the current live decision. + +### 1. Appeal type + +**Purpose** + +Appeal type is the main top-level discriminator for participation behaviour. + +**Effect on decision** + +- determines whether the case is excluded entirely +- determines whether appeal-type-specific rules apply +- determines whether Householder, CPO, ROW, Advert, or consultation-specific logic is used +- affects which date fields are relevant in some branches + +### 2. Appeal type family + +**Purpose** + +Appeal type family is used for broad exclusion rules. + +**Effect on decision** + +- certain families are blocked from representation participation regardless of other conditions +- explicit excluded appeal type IDs are also blocked even where family grouping might otherwise allow them + +Current excluded families/IDs are characterized through `canShowRepresentationButtonForAppealType(...)`. + +### 3. Specialist process + +**Purpose** + +Specialist process acts as an overlay for certain appeal types, especially ROW and Advert. + +**Effect on decision** + +- determines whether ROW is treated as hearing vs non-hearing +- determines whether Advert is treated as written reps, hearing, or other +- can change whether date gating applies +- can change whether participation is allowed, blocked, or permissively allowed by fallback + +### 4. Participant type + +**Purpose** + +Some participation rules depend on who the actor is. + +**Effect on decision** + +- Householder is LPA-only +- Advert written reps is LPA-only +- non-LPA Householder unavailable state also triggers message suppression + +### 5. Representation window + +**Purpose** + +For general cases, participation depends on whether the current representation period is open. + +**Effect on decision** + +- controls whether general participation is available +- controls blocked/ended-state behaviour for many cases +- uses field fallbacks in general resolution logic, but not all appeal-type exceptions use those fallbacks + +### 6. Consultation window + +**Purpose** + +Some participation is treated as consultation activity rather than general representation activity. + +**Effect on decision** + +- consultation routes are controlled by consultation open/close dates +- consultation behaviour is separate from the general representation window path + +### 7. Date state + +**Purpose** + +The system distinguishes between currently open, expired, future, and incomplete/missing windows. + +**Effect on decision** + +- open windows allow participation where no other exception blocks it +- expired windows block date-gated participation +- future windows also block date-gated participation +- missing/incomplete dates currently block some date-gated paths + +### 8. CRM compatibility variants + +**Purpose** + +Historic CRM field variants are part of the live contract. + +**Effect on decision** + +- different consumers can reach different results depending on which field variant is present +- canonical vs misspelled specialist-process fields are especially important for ROW and Advert +- start-date and due-date variants can change participation availability when specific branches do not use the broader fallbacks + +### 9. Field presence / absence + +**Purpose** + +Some branches make permissive decisions when data is absent; others make blocking decisions. + +**Effect on decision** + +- missing ROW specialist-process data currently falls through to allowed behaviour +- missing Advert specialist-process data currently falls through to blocked behaviour +- missing date data blocks CPO and ROW hearing paths + +### 10. String vs numeric appeal type handling + +**Purpose** + +Appeal type format affects which special-case branch executes. + +**Effect on decision** + +- some helper paths coerce string values safely +- some consumer `switch` branches depend on numeric values and can be bypassed by string input +- this is characterized live behaviour and must be preserved unless intentionally changed + +--- + +## Rule Catalogue + +## Core Rules + +### Excluded appeal categories + +Participation is blocked entirely for the currently excluded appeal-type families: + +- `ELECTRICITY_ACT` +- `TRANSPORT_WORKS` +- `HARBOUR_REVISION_ORDER` +- `WAYLEAVE` +- `NON_VALIDATION` + +Participation is also blocked for explicit excluded appeal type IDs: + +- `846040020` +- `846040023` + +### General participation window model + +For most non-excluded cases: + +- participation is generally available +- participation depends on the relevant window being open +- once the period is no longer open, participation becomes unavailable + +The general representation-window resolver currently uses: + +- start: `pinswg_startdate` or `pinswg_startdates` or `pinswg_applicationacceptedasvalid` +- end: `pinswg_finalcommentsduedate` or `pinswg_endofrepresentationperiod` + +### Permissive default model + +For many non-special cases, once broad exclusion rules are passed, behaviour is permissive unless a specific exception blocks participation. + +This permissive model is important in explaining current ROW non-hearing and missing-data fallbacks. + +--- + +## Appeal-Type Exceptions + +### Householder + +Current live behaviour: + +- participation is LPA-only +- non-LPA actors are blocked +- blocked explanatory messaging is suppressed for non-LPA Householder users + +### CPO + +Current live behaviour: + +- participation is controlled by a CPO-specific date window +- the CPO rule uses `pinswg_startdate` → `pinswg_statementduedate` +- it does not broaden to general start-date fallbacks +- missing, future, or expired window values block participation + +### ROW + +Current live behaviour: + +- hearing specialist process is date-gated +- non-hearing specialist process values are generally allowed +- missing specialist-process information currently falls through to permissive behaviour +- only `pinswg_startdate` and `pinswg_finalcommentsduedate` are used for hearing date gating + +### Advert + +Current live behaviour: + +- written reps is LPA-only +- hearing is allowed for LPA and non-LPA +- other specialist-process values are blocked +- Advert is not currently date-gated + +### Consultation participation + +Current live behaviour: + +- consultation participation is handled separately from general representation participation +- consultation availability depends on consultation open/close dates + +--- + +## Specialist Process Overlays + +### Hearing + +- ROW hearing is date-gated +- Advert hearing is allowed and not date-gated + +### Written reps + +- Advert written reps is LPA-only + +### Other process-specific restrictions + +- ROW non-hearing remains permissive +- Advert non-allowlisted specialist-process values are blocked + +--- + +## Participant-Type Overlays + +### LPA-only behaviour + +Confirmed current LPA-only participation rules: + +- Householder participation +- Advert written reps participation + +### Non-LPA suppression behaviour + +Confirmed current suppression rule: + +- non-LPA Householder users receive neither CTA nor blocked explanatory message + +--- + +## Unavailable-State Behaviour + +Current unavailable-state handling is part of the decision model. + +### Blocked messaging + +When a participation branch is in scope and the relevant path is unavailable, the portal may show blocked explanatory text. + +### Ended-period messaging + +Some consumers also render period-ended messaging once a participation period is considered closed. + +### Suppression rules + +Blocked messaging is currently suppressed for non-LPA Householder users. + +### Important note + +Unavailable-state rendering is not fully centralized. This contributes to a small number of current compatibility-sensitive differences in how blocked and ended states are expressed. + +--- + +## Decision Tree + +The current live decision can be reconstructed at a business-logic level as follows. + +1. **Is this appeal type excluded from representation participation?** + - If yes → participation unavailable. + - If no → continue. + +2. **Is this case currently being handled as a consultation route?** + - If yes → use consultation availability rules based on consultation dates. + - If no → continue with general representation availability. + +3. **Is the general participation route in scope and is the relevant window open?** + - If no → participation unavailable or ended-state behaviour may apply. + - If yes → continue. + +4. **Does this appeal type have a specific exception rule?** + - Householder → allow only LPA. + - CPO → allow only if CPO window (`startdate` → `statementduedate`) is open. + - ROW → use specialist-process overlay. + - Advert → use specialist-process overlay. + - Other types → permissive allow. + +5. **If specialist process is relevant, what process applies?** + - ROW hearing → date-gated. + - ROW non-hearing → allowed. + - Advert written reps → LPA-only. + - Advert hearing → allowed. + - Advert other values → blocked. + +6. **If participation is unavailable, should unavailable-state messaging be shown or suppressed?** + - non-LPA Householder → suppress blocked message. + - otherwise → blocked and/or ended messaging may be shown depending on consumer and date state. + +This decision tree describes the live logic conceptually. It does not imply that the current implementation is centralized. + +--- + +## Behaviour Matrix Summary + +This section intentionally summarizes the characterized matrix rather than reproducing every row. + +| Scenario | Current summarized behaviour | +| -------------------------- | ---------------------------------------------------------------------------------- | +| General cases | Participation generally available while the relevant representation window is open | +| Excluded categories | Participation unavailable regardless of other conditions | +| Householder | LPA-only participation; non-LPA blocked; blocked message suppressed for non-LPA | +| CPO | Participation date-gated using a CPO-specific due date | +| ROW hearing | Participation allowed only while the ROW hearing window is open | +| ROW non-hearing | Participation generally available | +| Advert written reps | LPA-only participation | +| Advert hearing | Participation available for LPA and non-LPA | +| Advert other process types | Participation unavailable | +| Consultation participation | Controlled separately by consultation dates | + +For the full characterization detail, maintainers should refer back to the investigation outputs and phase22 tests. + +--- + +## Known Compatibility Constraints + +### CRM Field Variants + +The following are confirmed compatibility-sensitive inputs and must be preserved as live contract. + +#### Specialist-process variants + +- `pinswg_specialistcaseprocess` +- `pinswg_speacialistcaseprocess` + +These are not interchangeable in current live behaviour. + +#### Start-date variants + +- `pinswg_startdate` +- `pinswg_startdates` +- `pinswg_applicationacceptedasvalid` + +These are used differently across general vs exception-specific paths. + +#### Due-date variants + +- `pinswg_statementduedate` +- `pinswg_finalcommentsduedate` +- `pinswg_endofrepresentationperiod` + +These are not uniformly applied across all consumers and exception paths. + +These variants are compatibility requirements, not cleanup targets. + +### String vs Numeric Appeal Types + +Current behaviour is format-sensitive. + +- some top-level exclusions still apply because helper logic coerces numeric values +- some appeal-type-specific branches depend on numeric `switch` matching +- as a result, string values such as `"846040015"` or `"846040018"` can bypass special-case logic and fall through to permissive behaviour + +This behaviour is characterized and must not be changed accidentally. + +### Preserved Consumer Divergence + +Current live behaviour is not fully standardized across consumers. + +Known divergence currently exists between: + +- case summary behaviour +- search-results behaviour +- extracted domain helpers + +These differences must be treated as preserved live behaviour unless an explicit business decision authorizes standardization. + +--- + +## Known Divergences + +### 1. ROW misspelled specialist-process behaviour + +**Observed behaviour** + +- summary uses only `pinswg_specialistcaseprocess` for ROW +- search uses normalized fallback across canonical + misspelled fields +- where only the misspelled field is present with hearing value, summary can allow participation while search date-gates/block it + +**Why it matters** + +The same underlying case can appear available in one portal area and unavailable in another. + +**Status** + +Characterized and preserved. + +### 2. Advert canonical vs misspelled specialist-process behaviour + +**Observed behaviour** + +- summary reads only `pinswg_speacialistcaseprocess` +- search uses canonical-first normalization +- canonical-only field population can block summary while allowing search + +**Why it matters** + +Portal behaviour depends on which CRM field variant is populated. + +**Status** + +Characterized and preserved. + +### 3. Conflicting field precedence for Advert + +**Observed behaviour** + +- when both canonical and misspelled specialist-process fields exist with different values, summary uses the misspelled field directly +- search gives precedence to the canonical field + +**Why it matters** + +Conflicting field values produce deterministic user-facing divergence. + +**Status** + +Characterized and preserved. + +### 4. CPO ended-message behaviour + +**Observed behaviour** + +- CPO participation gating uses `pinswg_statementduedate` +- blocked-state date display also uses the CPO due date +- ended-message closure checks still rely on general ended-period logic using `pinswg_finalcommentsduedate` + +**Why it matters** + +Participation can be blocked using one deadline while ended-period messaging is determined differently. + +**Status** + +Characterized; business intent still needs validation. + +--- + +## Characterization Coverage + +### Existing characterization tests + +The repository already contains phase22 characterization tests covering key areas of this behaviour, including: + +- `tests/phase22/representation-row-entry-rule.test.cjs` +- `tests/phase22/representation-advert-entry-rule.test.cjs` +- `tests/phase22/representation-cpo-entry-rule.test.cjs` + +### Behaviour currently protected by tests + +Existing tests cover, among other things: + +- ROW hearing date gating +- ROW non-hearing permissive behaviour +- ROW canonical vs misspelled specialist-process divergence +- ROW string appeal-type bypass behaviour +- Advert written reps LPA-only behaviour +- Advert hearing availability +- Advert blocking for other process values +- Advert canonical vs misspelled divergence +- Advert conflicting precedence divergence +- Advert string appeal-type bypass behaviour +- CPO open / future / expired / missing date behaviour +- CPO refusal to broaden to fallback start fields + +### Behaviour still requiring additional validation + +The following remain especially valuable for ongoing protection: + +- summary vs search unavailable-state rendering differences +- Householder blocked-message suppression +- consultation availability behaviour +- CPO ended-message inconsistency +- broader excluded-family coverage at documentation and test level + +--- + +## Business Validation Questions + +The following open questions emerged from characterization. + +1. Should the general rule remain: participation is available only while the relevant participation period is open? +2. Should Householder participation remain LPA-only? +3. If Householder participation is unavailable, should users be shown an explanation? +4. Should CPO use a separate participation deadline from most other cases? +5. Should all CPO unavailable/ended messages use the same deadline consistently? +6. Should ROW hearing remain date-gated? +7. Should ROW non-hearing remain generally available? +8. What should happen when ROW process information is missing or unclear? +9. Should Advert written reps remain LPA-only? +10. Should Advert hearing remain available to all participant types? +11. Should Advert other process types remain blocked? +12. Should consultation participation remain intentionally separate from general representation participation? +13. Should missing process information ever default to allowed participation? +14. Should portal areas interpret the same process information consistently when different compatibility fields are populated? +15. Should string and numeric appeal-type inputs behave the same way? + +--- + +## Architectural Conclusions + +The characterization work supports the following conclusions. + +1. The portal is making **one broad participation-availability decision**, not a set of unrelated visibility decisions. +2. The current behaviour is best described as a **coherent policy with layered exceptions**. +3. The policy has grown **organically over time**, which explains the mix of structured rules and compatibility-sensitive divergence. +4. Future work in this area should be driven by **business decision modelling**, not by superficial code cleanup. +5. CRM field variants, string-vs-number input behaviour, and consumer divergence are all part of the current live contract and must be preserved unless a deliberate behaviour change is approved. + +--- + +## Related Documentation + +- `docs/representation-participation-business-review.md` +- `lib/domain/representation-policy/README.md` +- `docs/query-profile-compatibility.md` diff --git a/docs/representation-participation-business-review.md b/docs/representation-participation-business-review.md new file mode 100644 index 00000000..22fa9b52 --- /dev/null +++ b/docs/representation-participation-business-review.md @@ -0,0 +1,229 @@ +# Representation Participation Rules – Business Review + +## Purpose + +This document describes the portal’s current observed behaviour when deciding whether someone can take part in a representation or consultation process. + +It is intended for: + +- product owners +- business analysts +- subject matter experts +- service owners + +This is **not** a technical design document. + +It does not describe how the system is implemented. + +Its purpose is to help the business confirm whether the portal currently behaves as intended. + +--- + +## Plain English Summary + +The portal appears to be making one broad decision: + +> Can this participant take part in this case at this point in the process? + +Current observed behaviour suggests that the answer depends on: + +- case type +- process type +- participant type +- whether the participation period is open +- whether the case is being treated as a consultation + +The portal mostly follows a general pattern, but some case types appear to have special exceptions. + +Some differences in current behaviour may also be historical rather than intentional. + +--- + +## General Cases + +Current observed behaviour suggests: + +- participation is generally available for most case types +- participation is only available while the relevant participation period is open +- once that period ends, participation is no longer available + +### Business validation questions + +1. Is this still the correct general rule? +2. Should participation normally depend on an open participation period? + +--- + +## Householder Cases + +Current observed behaviour suggests: + +- Local Planning Authorities can participate +- other participant types cannot participate +- where participation is unavailable, users may not always be shown an explanatory message + +### Business validation questions + +1. Should Householder participation remain restricted to Local Planning Authorities only? +2. If participation is unavailable, should users be shown an explanation? + +--- + +## Compulsory Purchase Order Cases + +Current observed behaviour suggests: + +- participation is controlled by a specific participation period +- this case type appears to use a different participation deadline from most other cases +- participation messages may not always use that deadline consistently + +### Business validation questions + +1. Is a separate participation deadline expected for these cases? +2. Should all participation messages for these cases use the same deadline consistently? + +--- + +## Rights of Way Cases + +Current observed behaviour suggests: + +### Hearing cases + +- participation is only available during a defined participation period + +### Non-hearing cases + +- participation is generally available + +### Where process information is missing or unclear + +- participation may still be treated as available + +### Business validation questions + +1. Should hearing cases be restricted to a participation period? +2. Should non-hearing cases remain generally available? +3. What should happen if process information is missing or unclear? +4. Should missing or unclear process information ever prevent participation? + +--- + +## Advertisement Cases + +Current observed behaviour suggests: + +### Written representation cases + +- Local Planning Authorities may participate +- other participant types may not participate + +### Hearing cases + +- participation is available to all participant types + +### Other process types + +- participation is not available + +### Business validation questions + +1. Is this behaviour correct? +2. Should written representation cases remain restricted to Local Planning Authorities? +3. Should hearing cases remain open to all participant types? +4. Should other process types remain blocked? + +--- + +## Consultation Cases + +Current observed behaviour suggests: + +- some participation routes are treated as consultations rather than representations +- consultation participation is controlled by consultation dates +- consultation participation appears to be handled separately from general representation participation + +### Business validation questions + +1. Is consultation participation intentionally separate from representation participation? +2. Should consultation dates control availability? + +--- + +## Missing or Conflicting Information + +Current observed behaviour suggests that participation can depend on how process information is available. + +In some cases: + +- missing information may still allow participation +- incomplete information may block participation +- different portal areas may interpret the same situation differently + +### Business validation questions + +1. If process information is missing, should participation be: + - allowed + - blocked + - decided another way +2. If process information is conflicting, how should the portal decide? +3. Are there cases where missing information should always prevent participation? + +--- + +## Current Known Differences Between Portal Areas + +Current observed behaviour suggests that some portal areas may interpret the same case information differently. + +Examples of this include situations where: + +- one area treats process information as sufficient to allow participation +- another area treats the same case as needing further restriction +- unavailable messages may not always be shown in the same way + +These differences may be historical rather than intentional. + +### Business validation questions + +1. Should all portal areas interpret the same participation information in the same way? +2. Are any current differences intentional? +3. If differences are not intentional, which behaviour should be treated as correct? + +--- + +## Business Review Checklist + +Use this table to record whether the current observed behaviour matches business expectation. + +| Area | Current Behaviour | Agree? | Notes | +| ------------------------------- | ---------------------------------------------------------------------------------------------- | ------ | ----- | +| General cases | Participation generally available while the participation period is open | | | +| Householder | Only Local Planning Authorities can participate | | | +| CPO | Participation controlled by a separate participation deadline | | | +| ROW hearing | Participation available only during the relevant participation period | | | +| ROW non-hearing | Participation generally available | | | +| Advert written reps | Only Local Planning Authorities can participate | | | +| Advert hearing | All participant types can participate | | | +| Advert other process types | Participation not available | | | +| Consultation | Participation controlled separately by consultation dates | | | +| Missing process information | Participation may still be allowed in some cases | | | +| Conflicting process information | Different portal areas may currently interpret this differently | | | +| Ended participation messages | Participation becomes unavailable, but explanation/messages may not always be fully consistent | | | + +--- + +## Important Notes + +- This document describes **current observed behaviour**. +- Some current behaviour may exist for historical reasons. +- This document is intended for validation, not implementation. +- No changes should be made on the basis of this document alone. +- Any future change should be confirmed through business decision-making and protected by characterization before implementation. + +--- + +## Related Technical Documentation + +For the technical characterization and compatibility details, see: + +- `docs/representation-participation-availability.md` diff --git a/memory-bank/change-log.md b/memory-bank/change-log.md index 7cca28ff..e6072dbf 100644 --- a/memory-bank/change-log.md +++ b/memory-bank/change-log.md @@ -18,6 +18,41 @@ Follow-ups: --- +### CL-2026-06-18-RPA-DOCS: representation participation availability documentation + context update + +date: 2026-06-18 +author: Cline +scope: `docs/representation-participation-availability.md`, `docs/representation-participation-business-review.md`, `context/current-platform-state.md`, `memory-bank/{techContext,productContext,open-questions,change-log}.md` +type: change +rationale: Preserve the completed Representation Participation Availability investigation in repository documentation and project context so future contributors do not need to repeat the same discovery work. +impact: Documentation/context only; improves architectural clarity and business-validation readiness; no runtime, auth, i18n, or API behaviour change. +status: completed + +Summary: + +- Added first-class technical documentation for Representation Participation Availability. +- Added a plain-English business review document for product/business/SME validation. +- Updated platform and memory-bank context to record: + - the stream as complete from a technical discovery/documentation perspective + - the architectural conclusion that representation participation is one coherent decision model with layered exceptions + - the current state as awaiting business validation before further representation-policy adoption/expansion/change work + - the next likely discovery candidate: Case Lifecycle / Status Decision Model Discovery +- Added a concise open-questions entry pointing business stakeholders to the new review/technical documentation. + +Validation: + +- Documentation/context update only. +- No application code changed. +- No tests changed. +- Lint/tests skipped because this was documentation-only work. + +Follow-ups: + +- Review `docs/representation-participation-business-review.md` with business stakeholders. +- Do not broaden representation-policy boundaries further until validation outcomes are agreed. + +--- + ### CL-22541: breadcrumb/back-link route-state helper extraction (`va/adv/ads/key`) date: 2026-04-09 diff --git a/memory-bank/open-questions.md b/memory-bank/open-questions.md index 7cd90ee5..c146c25e 100644 --- a/memory-bank/open-questions.md +++ b/memory-bank/open-questions.md @@ -88,3 +88,37 @@ Technical lead + DevOps owner Decision deadline: Before runtime-affecting refactor or next deployment process update + +--- + +### Q-004: Representation Participation Availability business validation + +date: 2026-06-18 +author: Cline +scope: representation participation availability across summary/search/domain policy +type: question +rationale: Technical characterization is complete, but several compatibility-sensitive behaviours may be historical rather than intentional and need business confirmation before any further representation-policy adoption or behaviour change work. +impact: User-facing participation availability, blocked messaging, cross-portal consistency, and future domain-boundary decisions. +status: open + +Question: +Which current representation participation behaviours are intended business rules, and which are historical compatibility behaviours only? + +Needed from: +Product owner + business analyst + relevant SME/CRM data owner + +Decision deadline: +Before any further representation-policy adoption, expansion, normalization, or behavioural change work + +Current context: + +- Technical characterization and documentation are now recorded in: + - `docs/representation-participation-availability.md` + - `docs/representation-participation-business-review.md` +- Business validation is especially needed for: + - Rights of Way behaviour when process information is incomplete or stored differently + - Advertisement behaviour when process information is incomplete or conflicting + - whether all portal areas should behave consistently + - Householder blocked-message suppression + - CPO ended-message / deadline consistency + - missing or conflicting process information handling diff --git a/memory-bank/productContext.md b/memory-bank/productContext.md index 31bf49f0..1919c65b 100644 --- a/memory-bank/productContext.md +++ b/memory-bank/productContext.md @@ -27,9 +27,25 @@ - Case summary UI varies by appeal type and case attributes. - Representation actions are conditionally shown by appeal type, role, and date windows. +- Representation participation now appears to form one broader business decision model: whether a participant can engage in representation or consultation activity for a case at that point in the process. - Locale-sensitive behavior affects links, routes, labels, and email template choice. - New-case-reference notifications include preferred-language checks before template selection. +## Current representation participation state + +- Technical discovery/documentation for Representation Participation Availability is complete. +- The current behaviour is best understood as a coherent participation-availability policy with layered appeal-type, process-type, participant-type, consultation, and date-window exceptions. +- Business validation is still required before any further representation-policy adoption, expansion, or behavioural change work. +- Reference documents: + - `docs/representation-participation-availability.md` + - `docs/representation-participation-business-review.md` + +## Likely next discovery candidate + +- Case Lifecycle / Status Decision Model Discovery + - expected focus: case progress, stages, statuses, closed states, dashboard grouping, and lifecycle messaging + - should be treated as discovery-only pending review of the new representation participation documentation + ## Important user-facing behaviors - Welsh route aliases are mapped in `next.config.js` and must remain in sync with page behavior. diff --git a/memory-bank/techContext.md b/memory-bank/techContext.md index b65a3527..359dd29d 100644 --- a/memory-bank/techContext.md +++ b/memory-bank/techContext.md @@ -43,6 +43,18 @@ - Formatting conventions from `.prettierrc`: 4 spaces, no trailing commas. - Prisma client generation script available: `npm run prisma:generate`. +## Current domain documentation status + +- Representation Participation Availability has now been documented as a first-class technical domain characterization. +- Technical source-of-truth: + - `docs/representation-participation-availability.md` +- Business validation companion: + - `docs/representation-participation-business-review.md` +- Current architectural conclusion: + - representation participation is best understood as one coherent decision model with layered exceptions + - known consumer divergences and CRM compatibility behaviours are part of the current live contract + - future technical adoption/expansion work should wait for business validation before changing behaviour or broadening policy boundaries + ## CI/CD and deployment artifacts - `azure-pipelines.yml` exists (legacy-looking Node 10 build pipeline).