pedwfrontend/context/api-grouping-adoption-roadmap.md

# API Grouping Adoption Roadmap

## Status

Planning only.

Pilot status update (2026-06-25):

- first additive grouping façade pilot implemented for watched-case APIs under `pages/api/subscriptions/`
- first internal consumer (`actions/services/portalDirectService.js` watched-case methods) now targets the grouped façade routes
- the active watched-case vertical slice now includes grouped adoption for both normal watched-case reads and proxy watched-case reads used by the current UI journey
- second additive grouping façade vertical slice implemented for the active published-documents metadata journey under `pages/api/documents/`
- active published-document metadata consumer (`actions/services/searchDirectService.js`) now targets grouped documents façade routes for details, paged details, and document-type reads
- published document download remains on the existing grouped runtime path `pages/api/documents/download/[id].js`
- legacy document metadata endpoint routes remain canonical and stable behind the additive façade wrappers
- third additive grouping façade vertical slice implemented for the active Public Search results journey under `pages/api/search/`
- active public search consumer (`actions/services/searchDirectService.js`) now targets grouped search façade routes for the proven in-scope public results path
- legacy public search endpoint routes remain canonical and stable behind the additive façade wrappers
- legacy watched-case endpoint routes remain canonical and stable
- no old route removal or migration has occurred
- runtime behaviour is intended to remain unchanged because the grouped routes delegate to the existing handlers

This document describes how PEDW could **gradually adopt** the future journey-owned API grouping model over time without disrupting existing functionality.

It is an **architectural roadmap only**.

It does **not** recommend implementation, migration, route movement, route renaming, API deletion, consolidation, contract change, or behaviour change.

---

## Required Context Read

The following files were read before drafting this roadmap:

- `context/api-grouping-plan.md`
- `context/api-route-map.md`
- `context/journey-architecture-map.md`
- `context/portal-api-platform-assessment.md`
- `context/architecture.md`
- `context/integration-map.md`
- `memory-bank/change-log.md`

---

## Files Modified

- `context/api-grouping-adoption-roadmap.md`
- `memory-bank/change-log.md`

---

## Findings

- The completed architecture programme already established that PEDW’s API platform is structurally smaller than its route count first suggests.
- The main maintainability problems are already known:
    - findability
    - ownership clarity
    - consistency
    - reuse discipline
- The current runtime is stable even though folder ownership is historically mixed.
- The current top-level API shape still reflects historical growth more than clean journey ownership, especially in:
    - `pages/api/endpoint`
    - `pages/api/file`
- The route map, journey map, and API grouping plan already support a **journey-first conceptual model** without requiring physical route movement.
- The strongest safe planning assumption is therefore:

> PEDW should adopt future journey-owned API grouping gradually through future development guidance, improved documentation, and incremental consistency rather than large-scale migration.

---

## Adoption Philosophy

PEDW should favour **gradual evolution** over large structural change.

Why:

1. The current platform is already live and stable.
2. Many APIs are contract-critical even where current folder ownership is historically inconsistent.
3. Several route families are orchestration-heavy and cross multiple integrations, making physical reorganisation riskier than conceptual reclassification.
4. The completed architecture programme has already shown that the main problem is not missing discovery; it is making ownership and maintainability clearer.

For that reason, PEDW should prefer:

- gradual evolution
- behaviour preservation
- contract preservation
- incremental consistency
- reuse of shared helpers
- documentation-led clarity

over:

- large restructures
- wholesale folder moves
- API rewrites
- mass renaming
- cosmetic reorganisation without delivery value

Adoption guidance:

- existing APIs should remain stable
- existing routes should continue to work
- existing URLs should continue to work
- existing contracts should continue to work
- future grouping should emerge naturally as future work touches relevant areas

---

## Adoption Stages

### Stage 1 — Current State

#### Purpose

Record today’s platform as the baseline for future adoption thinking.

#### Current State Summary

- the API platform reflects historical growth
- current top-level folders remain implementation hosts rather than clean business ownership boundaries
- ownership is mixed across business journeys, integrations, and shared support concerns
- the runtime is stable and should be preserved

#### Architecture Notes

- `endpoint/` remains the main historical CRM relay catch-all
- `file/` remains the main secondary storage/orchestration catch-all
- smaller families such as `admin/`, `documents/`, and `auth/` are more coherent, though not always perfectly isolated
- shared helpers and route patterns already exist and provide a safer basis for future consistency than folder movement alone

#### Roadmap Meaning

Stage 1 is not a problem statement that justifies migration.

It is the baseline that explains why PEDW should improve ownership clarity **without destabilising the current runtime**.

---

### Stage 2 — Future Development Guidance

#### Purpose

Guide future API work so that PEDW gradually becomes more journey-owned over time without requiring broad reorganisation.

#### Guidance

- new APIs should naturally follow journey ownership
- new work should start from the journey-owned model before considering current folder habits
- new APIs should reuse existing shared helpers where suitable
- avoid creating additional catch-all folders
- avoid copying historical direct-wrapper patterns where shared helpers already exist
- keep integrations behind journey-owned API boundaries conceptually, even when current files remain where they are
- preserve published-document and draft-storage distinctions
- preserve established auth/session and authorization boundaries

#### Practical Interpretation

This stage does **not** mean:

- move existing routes now
- rename existing routes now
- rewrite older APIs now

It means:

- when future work naturally touches an area, use the future grouping plan as the conceptual ownership guide
- prefer additive clarity over structural churn

#### Proven pilot pattern

- The watched-case subscriptions pilot demonstrates a low-risk adoption shape:
    - add grouped façade routes in a journey-owned folder
    - delegate directly to the existing canonical handlers
    - keep existing routes live and unchanged
    - adopt the grouped routes incrementally through a carefully selected internal consumer first
- This should be treated as additive proof of the grouping model, not as rationalisation or deprecation.

#### Incremental adoption proof point

- The first internal consumer adoption is now in place for watched-case methods in `actions/services/portalDirectService.js`.
- For the intended watched-case journey scope, the active vertical slice now covers:
    - `getWatchedCases`
    - `getWatchedCasesProxy`
    - `createWatchedCases`
    - `deleteWatchedCases`
- Legacy watched-case endpoint routes remain the canonical implementations behind the façade.
- No route deprecation, removal, or contract migration has occurred.
- This validates that grouped journey-owned routes can be introduced first and then adopted incrementally without changing runtime behaviour.

#### Current pilot completion meaning

- For this pilot, a complete watched-case/subscriptions vertical slice means:
    - grouped subscriptions façade routes exist for the active watched-case journey calls
    - `actions/services/portalDirectService.js` targets those grouped routes for the active watched-case journey methods
    - legacy endpoint handlers remain present and canonical behind the façade
    - runtime behaviour remains unchanged through delegation
- `deletewatchedcasesproxy_api` remains a legacy/support route outside the grouped pilot scope because it is not part of the currently adopted normal watched-case service path.

#### Additional vertical-slice proof point — published documents

- The active published-documents journey now has a second complete additive grouping slice for metadata discovery only:
    - grouped façade routes exist for the active metadata/type reads under `pages/api/documents/`
    - `actions/services/searchDirectService.js` targets those grouped routes for:
        - `getSearchDocumentDetails`
        - `getSearchDocumentDetailsPaged`
        - `getSearchDocumentTypes`
    - legacy endpoint handlers remain present and canonical behind the façade:
        - `pages/api/endpoint/getsearchdocumentdetails_api.js`
        - `pages/api/endpoint/getsearchdocumentdetailspaged_api.js`
        - `pages/api/endpoint/getsearchdocumentTypes_api.js`
    - runtime behaviour remains unchanged through direct delegation and unchanged service-layer query contracts
- The active bounded audit also established that:
    - the current UI document journey is routed through `components/case/documents.js`
    - the current common metadata service layer is `actions/services/searchDirectService.js`
    - the existing grouped route `pages/api/documents/download/[id].js` remains the runtime download path and was intentionally left unchanged
    - `getsearchdocumenthistory_api.js` and `getsearchdocumenthistorypaged_api.js` remain present as legacy/support routes outside the active grouped adoption scope because they were not surfaced in the currently active UI journey
- For this documents slice, a complete vertical grouping slice means:
    - active document metadata/type journey calls have grouped façade routes
    - the active common service layer uses those grouped routes
    - legacy handlers remain present and canonical
    - download behaviour remains unchanged
    - no route migration, deletion, or contract change has occurred

#### Additional vertical-slice proof point — Public Search

- The active Public Search journey now has a third complete additive grouping slice for the bounded public results path:
    - grouped façade routes exist under `pages/api/search/` for the proven active service calls:
        - `basic-paged`
        - `advanced`
        - `advanced-paged`
        - `basic-details-paged`
    - `actions/services/searchDirectService.js` targets those grouped routes for:
        - `getBasicSearchPaged`
        - `getAdvancedSearch`
        - `getAdvancedSearchPaged`
        - `getBasicSearchDetailsPaged`
    - legacy endpoint handlers remain present and canonical behind the façade:
        - `pages/api/endpoint/getbasicsearchpaged_api.js`
        - `pages/api/endpoint/getadvancedsearch_api.js`
        - `pages/api/endpoint/getadvancedsearchpaged_api.js`
        - `pages/api/endpoint/getbasicsearchdetailspaged_api.js`
    - runtime behaviour remains unchanged through direct delegation and unchanged service-layer query contracts
- The bounded public-search audit also established that:
    - the active public results UI is driven through `components/search/searchresults.js`
    - the common service layer is `actions/services/searchDirectService.js`
    - paged basic results are active in the public results path
    - advanced search is in scope because `pages/advancedsearchresults.js` actively uses the advanced bootstrap route and the shared results UI actively uses the advanced paged route
    - paged search-detail expansion is in scope because the active results UI uses `getSearchDetailsPaged(...)`, which calls `getBasicSearchDetailsPaged(...)`
    - the following routes remain outside this grouped adoption scope because they belong to adjacent or excluded journeys rather than the active bounded public results path:
        - `getbasicsearch_api.js` (used for adjacent case-detail bootstrap and other non-results contexts)
        - `getbasicsearchdetails_api.js` (used for adjacent case-detail/bootstrap detail expansion)
        - address-search variants
        - DNS search variants
        - myportal search pages
- For this Public Search slice, a complete vertical grouping slice means:
    - active public results journey calls have grouped façade routes
    - the active common service layer uses those grouped routes
    - legacy handlers remain present and canonical
    - excluded adjacent search journeys remain unchanged
    - no route migration, deletion, or contract change has occurred

#### API Grouping Façade Rollout Checkpoint

- The first successful façade slices now establish a proven additive rollout pattern for:
    - subscriptions / watched cases
    - documents / published document metadata
    - public search results
- Proven runtime shape:

```text
UI journey
→ existing service layer
→ grouped façade route
→ legacy canonical handler
→ unchanged integration behaviour
```

- Proven implementation pattern:
    - audit the active journey path first
    - identify the existing owning/common service layer already used by that path
    - add grouped façade routes only for the proven in-scope active calls
    - implement each grouped route as a tiny wrapper that delegates directly to the existing legacy handler
    - keep the legacy handler as the canonical implementation
    - adopt the grouped route in the existing service layer only where the active journey path is proven and low-risk
    - leave adjacent, inactive, support, or orchestration-heavy routes out of scope unless separately justified
    - prove the slice with lightweight characterization tests covering delegation, service adoption, retained legacy handlers, and unchanged scope boundaries
- Important interpretation:
    - this checkpoint proves a safe rollout pattern for additive façade grouping
    - it does not approve route removal
    - it does not approve handler replacement
    - it does not approve broad migration
    - it does not approve grouping of more complex API families without another bounded audit

#### Vertical façade slice completion criteria

- A vertical façade slice should be treated as complete only when:
    - active journey paths are audited
    - grouped façade routes exist for the in-scope active routes only
    - the service layer adopts the grouped routes where safe and proven
    - legacy handlers remain present and canonical behind the façade
    - inactive or support routes are explicitly left out of scope where they are not part of the active adopted path
    - characterization tests prove façade delegation and service-layer adoption
    - characterization tests do not imply that legacy handlers can be removed
    - documentation records the exact scope, completion meaning, exclusions, and non-goals
- A slice is not complete merely because grouped files exist.
- Completion requires both bounded adoption evidence and explicit documentation of what remains outside scope.

#### Do not group yet criteria

- Grouping should be delayed when any of the following apply:
    - no clear service layer exists
    - active ownership is unclear
    - the route is orchestration-heavy
    - the route crosses storage + queue + CRM boundaries
    - the route is auth/session critical
    - the route is not proven active in a bounded current journey
    - grouping would require frontend refactor rather than additive service-level adoption
    - grouping would require contract change
- In these cases, documentation may still classify the area conceptually, but additive façade rollout should wait for a safer bounded slice.

#### Additional vertical-slice proof point — Case Details read journey

- The active Case Details read journey now has a fourth additive grouping slice for the proven case-specific read family only:
    - grouped façade routes exist under `pages/api/cases/` for the proven active reads:
        - `get-incident-by-id`
        - `get-case-message`
        - `get-linked-cases`
        - `get-sips-events`
        - `get-sips-media`
    - the existing service-layer adoption is split across the current owning read services:
        - `actions/services/caseDirectService.js` now targets grouped cases routes for:
            - `getIncidentbyID`
            - `getCaseMessage`
            - `getSIPSEvents`
            - `getSIPSMedia`
        - `actions/services/searchDirectService.js` now targets grouped cases routes for:
            - `getLinkedCases`
    - legacy endpoint handlers remain present and canonical behind the façade:
        - `pages/api/endpoint/getincidentbyid_api.js`
        - `pages/api/endpoint/getcasemessage_api.js`
        - `pages/api/endpoint/getlinkedcases_api.js`
        - `pages/api/endpoint/getsipsevents_api.js`
        - `pages/api/endpoint/getsipsmedia_api.js`
- The bounded audit established that the true active Case Details read journey is narrower than the full case page bootstrap:
    - public ticketnumber case pages (`pages/case/[ticketnumber].js`) still bootstrap primarily through the search family:
        - `getBasicSearch(...)`
        - `getSearchDetails(...)`
    - incident-id case pages (`pages/case/id/[incident].js` and `pages/myportal/case/id/[incident].js`) use the case-specific incident-id route
    - linked cases are actively loaded inside `components/case/summary.js` as a case-details read concern
    - SIPS events/media are active case-page enrichments for the relevant case type
    - documents remain a separate active journey owned by the documents slice through `components/case/documents.js` and `actions/services/searchDirectService.js`
- The following routes were intentionally left outside this grouped adoption scope:
    - `getbasicsearch_api.js`
    - `getbasicsearchdetails_api.js`
    - `getbasicsearchdetailspaged_api.js`
    - `getsearchdocumentdetails_api.js`
    - `getsearchdocumentdetailspaged_api.js`
    - `getsearchdocumentTypes_api.js`
    - `getcase_api.js`
    - `getcasebyid_api.js`
    - `getportalmoduledetails_api.js`
- Exclusion reasoning:
    - search bootstrap/detail-expansion routes remain part of Public Search or search-to-case bootstrap rather than the narrowed case-specific read family
    - published document metadata remains owned by the documents slice
    - `getcase_api.js` and `getcasebyid_api.js` are not proven active in the current case-page read path and remain adjacent/support routes
    - `getportalmoduledetails_api.js` is actively used in myportal aggregation/detail enrichment rather than the bounded public/myportal case-details page read slice itself
- For this Case Details slice, a complete vertical grouping slice means:
    - the proven case-specific read family has grouped façade routes
    - current owning service calls for that family target the grouped routes
    - adjacent search bootstrap and documents routes remain unchanged
    - legacy endpoint handlers remain canonical
    - no route migration, deletion, or contract change has occurred

#### Additional vertical-slice proof point — My Portal dashboard read / enrichment

- The active My Portal dashboard read / enrichment journey now has a fifth additive grouping slice for the proven CRM-backed dashboard read/enrichment family only:
    - grouped façade routes exist under `pages/api/myportal/` for the proven active reads:
        - `get-my-cases`
        - `get-my-lpa-cases`
        - `get-portal-module-details`
    - the existing owning service-layer adoption is split across the current dashboard read services:
        - `actions/services/portalDirectService.js` now targets grouped myportal routes for:
            - `getMyCases`
            - `getMyLPACases`
        - `actions/services/caseDirectService.js` now targets the grouped myportal route for:
            - `getPortalModuleDetails`
    - legacy endpoint handlers remain present and canonical behind the façade:
        - `pages/api/endpoint/getmycases_api.js`
        - `pages/api/endpoint/getmylpacases_api.js`
        - `pages/api/endpoint/getportalmoduledetails_api.js`
- The bounded audit established that the true active My Portal dashboard read/enrichment slice is narrower than the whole dashboard-related API surface:
    - `pages/myportal/index.js` is the principal authenticated dashboard loader
    - the active CRM read branch on that page is:
        - `getMyCases(loggedInUser)` or `getMyLPACases(lpaId)`
        - `getPortalModuleDetails(collectionName, caseID)` for detail-card enrichment fan-out
    - watched cases are already covered by the subscriptions slice through `getWatchedCases(loggedInUser)`
    - representation and awaiting-submission lists on this loader are blob-backed in the active path:
        - `getRepsFromBlob(thisSession.user.id)`
        - `getAwaitingSubmissionFromBlob(thisSession.user.id)`
    - account/bootstrap/auth routes remain upstream supporting concerns rather than part of this grouped read slice:
        - `getPortalLogin(...)`
        - `getPersonalAccount(...)`
        - `getSession(ctx)`
- The following routes were intentionally left outside this grouped adoption scope:
    - `getwatchedcases_api.js`
    - `getmyrepresentations_api.js`
    - `getawaitingsubmission_api.js`
    - storage/draft routes under `pages/api/file/**`
    - account/auth/session routes
- Exclusion reasoning:
    - watched-case reads are already owned by the completed subscriptions slice
    - `getmyrepresentations_api.js` and `getawaitingsubmission_api.js` were candidate routes to investigate, but they are not part of the proven active `pages/myportal/index.js` read path, which currently uses blob-backed representation and awaiting-submission retrieval instead
    - storage/blob routes remain explicitly out of scope for this read-only CRM façade slice
    - account/bootstrap/auth concerns remain out of scope by requirement and because they are not journey-owned dashboard CRM reads
- For this My Portal slice, a complete vertical grouping slice means:
    - the proven active CRM dashboard read/enrichment family has grouped façade routes
    - current owning service calls for that family target the grouped routes
    - subscriptions, storage/draft, and account/auth routes remain unchanged
    - legacy endpoint handlers remain canonical
    - no route migration, deletion, contract change, auth change, storage change, or behaviour change has occurred

#### Workflow boundary assessment checkpoint

- A bounded follow-on assessment of the remaining major API families established that the current additive façade pattern has a natural stop point.
- Main conclusion:

> The current façade rollout pattern is proven for bounded read-style journey families, but it should not be stretched across workflow/orchestration-heavy areas without a different design.

- Classification outcome from the representative family assessment:
    - **B — Possible façade candidate with caution**
        - account / registration / personal-details family, but only for a narrowly bounded future read-support slice
    - **C — Workflow / orchestration boundary**
        - notifications / email
        - appeals / drafts / finalisation
        - representations / drafts / finalisation
    - **D — Leave unchanged for now**
        - storage / blob / file operations
        - auth / session
        - admin / reporting
- What this means for rollout discipline:
    - the obvious low-risk read-family slices are now largely exhausted
    - remaining complex areas are complex because they cross identity, storage, queue, Notify, PDF, or finalisation boundaries
    - those areas do not meet the original checkpoint criteria for the same read-style façade rollout pattern
- Recommended next step after the completed façade baseline:
    - prefer a workflow/orchestration design assessment rather than another broad façade slice
    - if one more implementation slice is ever chosen first, the only reasonable candidate is a **narrow account read-support cautious slice** that excludes create/update/bootstrap-critical behavior

---

### Stage 3 — Documentation Maturity

#### Purpose

Improve maintainability through better documentation and route ownership guidance before any physical restructuring is ever considered.

#### Maturity Outcomes

- improved maintainer guidance
- improved route ownership clarity
- improved discoverability
- improved architectural consistency in how new work is described and reviewed
- better onboarding for contributors who need to understand where to start

#### Examples of Documentation-Led Adoption

- route ownership described by journey rather than folder alone
- shared platform helpers clearly separated from business APIs
- cross-cutting concerns such as auth and notifications documented as cross-cutting rather than forced into one business domain
- future grouping candidates captured as architectural guidance only

#### Important Constraint

This stage improves understanding **without moving routes**.

---

### Stage 4 — Future Opportunities

#### Purpose

Record possible future opportunities that could align with the grouping model if future work naturally justifies them.

#### Possible Future Opportunities

- selective grouping within areas already being changed for other approved reasons
- helper extraction where duplication remains visible
- improved shared platform reuse across journey-owned APIs
- stronger consistency in naming, ownership notes, and maintainer entry guidance
- clearer distinction between journey-owned APIs and shared/platform concerns

#### Constraint

These are **future opportunities only**.

They are not implementation recommendations.

They do not approve:

- route movement
- file movement
- migrations
- refactoring programmes
- API rewrites

---

## Adoption Principles

1. Preserve stable APIs.
2. Preserve contracts.
3. Preserve integrations.
4. Preserve CRM as the source of truth for CRM-owned business data.
5. Preserve Azure Storage ownership boundaries for draft-owned content.
6. Preserve established auth/session and authorization boundaries.
7. Prefer additive improvements.
8. Avoid unnecessary churn.
9. Improve findability first.
10. Improve consistency second.
11. Reuse shared helpers instead of duplicating infrastructure logic.
12. Use journey ownership as the conceptual guide for future work.
13. Consider physical grouping only when future approved work naturally touches an area.
14. Never move APIs solely for cosmetic reasons.
15. Do not force cross-cutting concerns into one journey-owned bucket.
16. Continue treating shared/platform capabilities as shared platform concerns rather than business-domain ownership.

---

## Decision Matrix

| Situation                   | Guidance                                                                                                                    |
| --------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| New API                     | Place it conceptually within the journey-owned model first, then implement using the safest existing route/helper patterns. |
| Existing stable API         | Leave unchanged.                                                                                                            |
| Existing API being enhanced | Consider alignment with journey ownership in documentation and helper usage, without assuming route movement.               |
| Shared infrastructure       | Keep in shared/platform concern classification.                                                                             |
| Cross-cutting concern       | Avoid forcing it into one journey if its real ownership is platform-wide or multi-journey.                                  |
| Historical catch-all folder | Treat it as a current host location, not as the preferred future ownership model.                                           |
| Orchestration-heavy route   | Classify conceptually by business journey, but preserve existing integration and sequencing behavior.                       |
| Documentation update        | Improve findability and ownership clarity before considering any structural change.                                         |
| Cosmetic restructuring idea | Do not pursue unless separately justified by future approved work.                                                          |

---

## Success Measures

Success should be understood qualitatively at architecture and maintainability level, not as an implementation delivery target.

Indicators of success:

- developers can find relevant APIs faster
- maintainers can identify likely owning journeys more easily
- shared infrastructure code is reused more consistently
- journey ownership becomes clearer in future documentation and code review discussions
- onboarding becomes simpler because route ownership is easier to explain
- maintenance effort is reduced through clearer patterns and less duplicated infrastructure logic
- future API additions align more naturally with business capability rather than historical folder drift

Avoid treating success as:

- number of routes moved
- number of folders renamed
- reduction in route count
- migration completion percentage

---

## Non-Goals

This roadmap explicitly does **not** approve or recommend:

- migrations
- implementation
- route movement
- route renaming
- API deletion
- API consolidation
- folder restructuring
- refactoring programmes
- mass renaming
- contract changes
- behaviour changes

This roadmap defines **architectural direction**, not delivery.

---

## Risks / Cautions

1. This roadmap is intentionally architecture-only.
2. It should not be mistaken for an implementation plan.
3. Stable runtime behavior matters more than conceptual neatness.
4. Several PEDW API areas remain orchestration-heavy and cross integration boundaries; conceptual grouping is safer than physical reorganisation.
5. `endpoint/` and `file/` remain historically important host folders even though they are not ideal future ownership concepts.
6. `auth/` and `notifications/` remain cross-cutting concerns and should not be over-simplified.
7. Dashboard-related APIs are aggregation-oriented and should be mapped back to owning journeys rather than treated as a separate long-term grouping target.
8. Future adoption should happen through natural change pressure, not through standalone cosmetic restructuring.

---

## Validation Performed

Manual synthesis only.

Performed:

- read the required roadmap context listed above
- reused the completed architecture programme as the evidence base
- reused the completed API grouping plan rather than reopening discovery
- kept the roadmap at architecture-roadmap level only

Not performed:

- no new API inspection
- no new API inventory
- no implementation design
- no migration proposal
- no refactor proposal
- no lint/tests, because this is documentation-only planning work

---

## Recommendation

Recommended next architecture planning document only:

### `context/api-maintainer-guidance-v2.md`

Suggested purpose:

- extend the existing maintainer guidance with clearer decision support for future API additions
- strengthen journey-owned ownership cues and shared-helper selection guidance
- improve onboarding and change-entry clarity without recommending implementation or restructuring

No implementation work is recommended from this roadmap alone.