docs: add current-state context pack and actionable sequence-b prompts
This commit is contained in:
+39
-6
@@ -102,7 +102,7 @@ Primary residual risks/gaps:
|
||||
3. **Logging hygiene variance**
|
||||
- Structured redaction exists in relay paths, but broader codebase logging still has uneven consistency.
|
||||
4. **i18n parity assurance remains process-heavy**
|
||||
- EN/CY parity relies heavily on manual discipline rather than automated parity checks.
|
||||
- EN/CY parity now has targeted automated coverage, but still relies on manual discipline for broader journey-level assurance and CI enforcement.
|
||||
|
||||
### Prioritised next steps
|
||||
|
||||
@@ -112,12 +112,13 @@ Primary residual risks/gaps:
|
||||
2. **Consolidate signed-request patterns (medium risk, high security clarity)**
|
||||
- Introduce a focused signed-request helper for hash-based/signed delete/get pathways currently repeated in service modules.
|
||||
- Keep existing hash/header semantics unchanged while reducing duplication.
|
||||
3. **Add high-value regression automation (high value)**
|
||||
- Add focused automated checks for:
|
||||
3. **Broaden high-value regression automation (high value)**
|
||||
- Initial focused checks are now in place for:
|
||||
- auth callback/redirect safety
|
||||
- one signed-delete negative path
|
||||
- one upload/document authorization negative path
|
||||
- one EN/CY route parity check
|
||||
- signed-delete negative path
|
||||
- upload/document authorization negative path
|
||||
- EN/CY route parity
|
||||
- Next, expand breadth/depth (more journey-level assertions and CI integration).
|
||||
4. **Perform targeted logging hardening in sensitive paths**
|
||||
- Continue replacing direct/verbose logging in `auth`, `file`, `email`, and account-sensitive endpoint paths with redacted structured logging patterns.
|
||||
5. **Introduce EN/CY parity CI checks**
|
||||
@@ -130,3 +131,35 @@ Primary residual risks/gaps:
|
||||
- **Sequence A (immediate):** Step 1 + Step 3 (fastest risk reduction per effort)
|
||||
- **Sequence B (next):** Step 2 + Step 4 (security/logging consistency consolidation)
|
||||
- **Sequence C (after):** Step 5 + Step 6 (institutionalise parity and reduce long-tail maintenance cost)
|
||||
|
||||
### Status update (2026-03-25)
|
||||
|
||||
- Sequence A targeted intent is now covered on this branch:
|
||||
- Step 1: direct-service consistency sweep completed for this bundle stream
|
||||
- Step 3: focused checks added for auth redirect safety and EN/CY rewrite parity, alongside existing signed-delete and upload/document negative-path coverage
|
||||
- Remaining work is primarily Sequence B and Sequence C scope.
|
||||
|
||||
### Cross-check update vs debt list and architect review (2026-03-25)
|
||||
|
||||
This architecture status has been cross-checked against:
|
||||
|
||||
- `memory-bank/debt-list.md`
|
||||
- `memory-bank/architect-review.md`
|
||||
|
||||
Current progress snapshot:
|
||||
|
||||
1. **Actions monolith decomposition** -> in progress with strong momentum
|
||||
- shared clients/helpers introduced (`relayClient`, `endpointClient`, `fileClient`, `fileRouteBuilder`) and adopted across key service modules
|
||||
- residual monolith risk remains until broader domain split is complete
|
||||
2. **API contract consistency** -> materially improved
|
||||
- large endpoint hardening footprint already delivered, with remaining long-tail cleanup still open
|
||||
3. **Sensitive logging hardening** -> partial
|
||||
- relay path improvements exist, but wider auth/email/file logging standardization remains open
|
||||
4. **Endpoint sprawl reduction** -> materially improved
|
||||
- repeated relay/proxy patterns reduced through helper reuse
|
||||
5. **i18n parity assurance** -> initial automation in place
|
||||
- targeted EN/CY rewrite parity checks now exist; CI-level institutionalization still recommended
|
||||
6. **High-risk regression automation** -> materially improved
|
||||
- focused auth redirect safety + signed-delete + upload/document negative-path + EN/CY parity checks now covered
|
||||
7. **Runtime canonicalization** -> still open
|
||||
- server entrypoint ambiguity (`server.js` vs `server/server.js`) remains an explicit follow-on architecture decision.
|
||||
|
||||
@@ -0,0 +1,35 @@
|
||||
# Current State Scorecard (2026-03-25)
|
||||
|
||||
Purpose: provide a single operational view of architecture/debt progress with evidence references.
|
||||
|
||||
## RAG Legend
|
||||
|
||||
- Green: materially addressed for current stream
|
||||
- Amber: partial progress, follow-on needed
|
||||
- Red: unresolved/high risk remains
|
||||
|
||||
## Scorecard
|
||||
|
||||
| Area | Status | Current position | Evidence |
|
||||
| --------------------------------- | ------ | -------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
|
||||
| API contract consistency | Green | Large endpoint clusters normalized on structured contracts with phase21 coverage. | `memory-bank/change-log.md` (endpoint hardening stream), `tests/phase21/endpoint-handler-contract.test.cjs` |
|
||||
| Actions/service decomposition | Amber | Shared clients and route builders introduced; monolith risk reduced but full domain split remains. | `actions/clients/*`, `actions/services/*`, `memory-bank/debt-list.md` |
|
||||
| Endpoint sprawl/proxy duplication | Amber | Shared relay forwarding and helper reuse reduced duplication; long-tail handlers still exist. | `pages/api/middleware/relayForwarding.js`, `context/architecture.md` |
|
||||
| High-risk automation | Green | Focused checks now cover auth redirect safety, signed-delete/upload negatives, and EN/CY rewrite parity. | `tests/phase22/auth-redirect-safety.test.cjs`, `tests/phase22/i18n-route-parity.test.cjs`, `tests/phase22/index.test.cjs` |
|
||||
| i18n parity assurance | Amber | Targeted parity checks in place; CI-level parity enforcement still pending. | `tests/phase22/i18n-route-parity.test.cjs`, `context/architecture.md` |
|
||||
| Logging redaction consistency | Amber | Relay-side structured redaction improved; broader auth/email/file logging hardening remains open. | `memory-bank/open-questions.md` (Q-001), `context/architecture.md` |
|
||||
| Runtime canonicalization | Red | `server.js` and `server/server.js` ambiguity not yet formally closed. | `memory-bank/architect-review.md`, `context/architecture.md` |
|
||||
|
||||
## Next execution focus
|
||||
|
||||
1. Sequence B: signed-request consolidation + logging hardening.
|
||||
2. Sequence C: CI-level i18n parity gates + endpoint long-tail reduction.
|
||||
3. Runtime canonicalization decision with explicit operational owner.
|
||||
|
||||
## Update cadence
|
||||
|
||||
- Update after every non-trivial architecture/debt slice.
|
||||
- Keep this file aligned with:
|
||||
- `context/architecture.md`
|
||||
- `memory-bank/debt-list.md`
|
||||
- `memory-bank/change-log.md`
|
||||
@@ -0,0 +1,101 @@
|
||||
# Sequence B Work Plan (2026-03-25)
|
||||
|
||||
Scope: implement the next architecture lane after Sequence A completion.
|
||||
|
||||
Sequence B objectives:
|
||||
|
||||
1. Consolidate signed-request patterns.
|
||||
2. Harden logging policy in sensitive paths.
|
||||
|
||||
## Workstream B1: Signed-request consolidation
|
||||
|
||||
### Goal
|
||||
|
||||
Reduce duplicate hash/header/method composition logic across service modules without changing behavior contracts.
|
||||
|
||||
### Target scope
|
||||
|
||||
- `actions/services/portalDirectService.js`
|
||||
- `actions/services/documentDirectService.js`
|
||||
- `actions/services/caseDirectService.js` (if signed routes exist)
|
||||
- shared client layer in `actions/clients/`
|
||||
|
||||
### Proposed implementation
|
||||
|
||||
1. Introduce a focused signed-request helper (or helper set) in `actions/clients/`:
|
||||
- signed GET
|
||||
- signed POST
|
||||
- signed DELETE
|
||||
2. Normalize hash/signing + header behavior through helper API.
|
||||
3. Migrate in bounded slices (module by module), preserving current catch semantics.
|
||||
|
||||
### Acceptance criteria
|
||||
|
||||
- No route URL/signature behavior regressions.
|
||||
- Existing signed flows preserve:
|
||||
- hash generation behavior
|
||||
- request method
|
||||
- required headers
|
||||
- error-return/catch contracts.
|
||||
- Phase22 behavioural tests expanded where relevant.
|
||||
|
||||
### Validation checklist
|
||||
|
||||
- `node tests/phase22/index.test.cjs`
|
||||
- `node tests/phase7/service-behaviour.test.cjs`
|
||||
- `npm run lint`
|
||||
|
||||
### Rollback plan
|
||||
|
||||
- Revert helper adoption commit(s) for affected service only.
|
||||
- Keep migrations bounded so each module rollback is isolated.
|
||||
|
||||
## Workstream B2: Logging hardening in sensitive paths
|
||||
|
||||
### Goal
|
||||
|
||||
Replace ad-hoc verbose logging in auth/email/file/account-sensitive paths with redacted, structured logs.
|
||||
|
||||
### Target scope
|
||||
|
||||
- `pages/api/auth/[...nextauth].js`
|
||||
- selected `pages/api/email/**`
|
||||
- selected `pages/api/file/**`
|
||||
- any adjacent shared helper used by these routes
|
||||
|
||||
### Proposed implementation
|
||||
|
||||
1. Define/confirm minimal redaction policy (link to `memory-bank/open-questions.md` Q-001).
|
||||
2. Introduce/standardize structured logger usage pattern for sensitive flows.
|
||||
3. Replace high-risk direct logs in bounded route clusters.
|
||||
|
||||
### Acceptance criteria
|
||||
|
||||
- No secrets/tokens/personal data in new logs.
|
||||
- Error correlation remains operationally useful.
|
||||
- Existing route behavior/contracts unchanged.
|
||||
|
||||
### Validation checklist
|
||||
|
||||
- `npm run lint`
|
||||
- targeted route-level negative-path checks for changed handlers
|
||||
- manual review of log payload fields against redaction policy
|
||||
|
||||
### Rollback plan
|
||||
|
||||
- Revert logging-hardening commit(s) by cluster.
|
||||
- Restore previous logger call sites if operational diagnostics regress.
|
||||
|
||||
## Delivery sequencing
|
||||
|
||||
1. B1 signed-request helper design + one pilot migration.
|
||||
2. B1 full module rollout (portal/document, then any remaining signed paths).
|
||||
3. B2 redaction policy confirmation.
|
||||
4. B2 auth cluster hardening.
|
||||
5. B2 file/email cluster hardening.
|
||||
|
||||
## Ownership and governance
|
||||
|
||||
- Track each slice in `memory-bank/change-log.md`.
|
||||
- Record policy decisions in `memory-bank/decisions.md`.
|
||||
- Escalate unresolved policy questions in `memory-bank/open-questions.md`.
|
||||
@@ -0,0 +1,29 @@
|
||||
# Test Coverage Map (High-Risk Flows) — 2026-03-25
|
||||
|
||||
Purpose: make current automated coverage explicit for high-risk architecture lanes and highlight remaining gaps.
|
||||
|
||||
## Coverage legend
|
||||
|
||||
- Covered: explicit automated assertion exists
|
||||
- Partial: some coverage exists, but not end-to-end or not broad enough
|
||||
- Gap: no focused automation currently identified for this flow
|
||||
|
||||
## Flow map
|
||||
|
||||
| Flow / risk area | Current status | Automated evidence | Notes / next gap |
|
||||
| --------------------------------------------------------------------- | ------------------------ | -------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
|
||||
| Auth redirect/callback safety | Covered | `tests/phase22/auth-redirect-safety.test.cjs` | Add callback URL edge-case matrix if auth flow expands. |
|
||||
| EN/CY rewrite parity (key routes) | Covered | `tests/phase22/i18n-route-parity.test.cjs` | Extend to wider rewrite inventory + CI gate. |
|
||||
| Signed-delete negative path(s) | Covered (targeted) | Existing phase21/phase22 slices (see `memory-bank/change-log.md`) | Expand to additional signed flows once helper consolidation lands. |
|
||||
| Upload/document authorization negative path | Covered (targeted) | Existing phase21/phase22 slices (see `memory-bank/change-log.md`) | Add broader journey-level checks around auth/session edge paths. |
|
||||
| Endpoint contract behavior (selected clusters) | Covered (broad targeted) | `tests/phase21/endpoint-handler-contract.test.cjs` | Continue long-tail cluster migration and assertions. |
|
||||
| Relay retry/timeout/logging policy behavior | Covered | `tests/phase21/relay-forwarding-hardening.test.cjs` | Keep updated if retry classification/policy changes. |
|
||||
| Service-layer behavior in migrated clients | Covered (targeted) | `tests/phase6/service-behaviour.test.cjs`, `tests/phase7/service-behaviour.test.cjs`, `tests/phase22/index.test.cjs` | Add new tests as signed-request helper abstraction is introduced. |
|
||||
| Runtime canonicalization behavior (`server.js` vs `server/server.js`) | Gap | N/A | Needs architecture decision before test strategy is meaningful. |
|
||||
|
||||
## Recommended next coverage increments
|
||||
|
||||
1. Add CI execution for phase22 aggregate (`tests/phase22/index.test.cjs`) if not already wired.
|
||||
2. Expand i18n parity checks to include broader route/key parity surface.
|
||||
3. Add a focused regression test set for signed-request helper once Sequence B B1 starts.
|
||||
4. Define minimum “high-risk flow” coverage bar in `memory-bank/open-questions.md` (Q-002 resolution).
|
||||
Reference in New Issue
Block a user