docs: add current-state context pack and actionable sequence-b prompts
This commit is contained in:
@@ -0,0 +1,57 @@
|
||||
# Refactor Session Handoff (Usable Prompt)
|
||||
|
||||
## Purpose
|
||||
|
||||
Copy/paste this directly into a new chat session to continue the current PEDW refactor stream with the right context and next-step planning.
|
||||
|
||||
## Copy/Paste Prompt
|
||||
|
||||
```
|
||||
You are continuing an in-flight refactor stream in the PEDW FrontEnd repository.
|
||||
|
||||
Before any analysis or code changes:
|
||||
1) Ask for the Azure DevOps work item ID (required).
|
||||
2) Create a new branch from `origin/SIPS-Development` prefixed with that ID (e.g. `US12345-progress-update` or `TASK67890-progress-update`).
|
||||
3) Confirm branch name, then continue.
|
||||
|
||||
Follow this order before implementing:
|
||||
1) Read `.clinerules/default-rules.md` and `.clinerules/CONTRIBUTING_AI.md`
|
||||
2) Read `GUARDRAILS.md`
|
||||
3) Read current-state docs:
|
||||
- `context/architecture.md`
|
||||
- `context/current-state-scorecard.md`
|
||||
- `context/next-work-plan-sequence-b.md`
|
||||
- `context/test-coverage-map.md`
|
||||
4) Read memory context:
|
||||
- `memory-bank/change-log.md` (latest entries)
|
||||
- `memory-bank/debt-list.md`
|
||||
- `memory-bank/architect-review.md`
|
||||
- `memory-bank/decisions.md`
|
||||
- `memory-bank/open-questions.md`
|
||||
|
||||
Then provide (based on what you read):
|
||||
1. Current state summary (what is done, what remains)
|
||||
2. Recommended next slice from this exact shortlist (pick one):
|
||||
- Slice B1.1: create shared signed-request helper(s) in `actions/clients/` and migrate one pilot path in `actions/services/portalDirectService.js`
|
||||
- Slice B1.2: migrate remaining signed flows in `actions/services/documentDirectService.js` to the shared signed helper(s)
|
||||
- Slice B2.1: auth logging hardening in `pages/api/auth/[...nextauth].js` (redacted structured logs, no behavior change)
|
||||
- Slice B2.2: file/email logging hardening in selected `pages/api/file/**` and `pages/api/email/**`
|
||||
3. Exact files to change
|
||||
4. Validation plan (lint + targeted tests + EN/CY parity + negative-path checks)
|
||||
5. Rollback plan
|
||||
|
||||
Constraints:
|
||||
- Preserve behavior unless explicitly requested otherwise
|
||||
- Do not weaken auth/session/CSP/security flows
|
||||
- Keep EN/CY parity
|
||||
- Keep scope to one bounded slice per commit
|
||||
- Update `memory-bank/change-log.md` for non-trivial changes
|
||||
|
||||
After proposing the slice, wait for approval before editing files.
|
||||
```
|
||||
|
||||
## Best use
|
||||
|
||||
- Start-of-day continuation
|
||||
- Branch handover between engineers/agents
|
||||
- Recovery after interrupted context window
|
||||
@@ -0,0 +1,183 @@
|
||||
# Refactor Slice Execution (Usable Prompts)
|
||||
|
||||
## Purpose
|
||||
|
||||
Copy/paste one of these prompts directly to execute a specific next slice (not just a template).
|
||||
|
||||
## Prompt A — Slice B1.1 (signed-request helper + pilot migration)
|
||||
|
||||
```
|
||||
Act as a senior architect + senior software engineer working in PEDW FrontEnd.
|
||||
|
||||
Before any analysis or code changes:
|
||||
1) Ask for the Azure DevOps work item ID (required).
|
||||
2) Create a new branch from `origin/SIPS-Development` prefixed with that ID (e.g. `US12345-signed-helper-pilot`).
|
||||
3) Confirm branch name and only then proceed.
|
||||
|
||||
Goal:
|
||||
Implement Slice B1.1 only: introduce shared signed-request helper(s) and migrate one pilot signed path in portal service.
|
||||
|
||||
Exact scope:
|
||||
- Add shared signed-request helper(s) in `actions/clients/` for signed GET/POST/DELETE execution.
|
||||
- Migrate one pilot signed flow in `actions/services/portalDirectService.js` to use the helper.
|
||||
- Do not migrate additional modules in this slice.
|
||||
|
||||
Mandatory context to read before coding:
|
||||
- `.clinerules/default-rules.md`
|
||||
- `GUARDRAILS.md`
|
||||
- `context/architecture.md`
|
||||
- `context/current-state-scorecard.md`
|
||||
- `context/next-work-plan-sequence-b.md`
|
||||
- `memory-bank/debt-list.md`
|
||||
- latest relevant `memory-bank/change-log.md` entries
|
||||
|
||||
Required output before edits:
|
||||
1. Scope and non-goals
|
||||
2. Risks and how they are contained
|
||||
3. Files to touch
|
||||
4. Acceptance criteria
|
||||
5. Validation checklist
|
||||
|
||||
Implementation constraints:
|
||||
- Smallest viable diff
|
||||
- Preserve API/route/public behavior
|
||||
- Preserve auth/session/security and EN/CY parity
|
||||
- No dependency churn unless required by scope
|
||||
- No unrelated cleanup
|
||||
|
||||
Validation minimum:
|
||||
- `npm run lint`
|
||||
- `node tests/phase22/index.test.cjs`
|
||||
- `node tests/phase7/service-behaviour.test.cjs`
|
||||
- explicit negative-path verification for sensitive flows
|
||||
|
||||
Completion output:
|
||||
1. Files changed
|
||||
2. Behavior parity statement
|
||||
3. Validation evidence (commands + pass/fail)
|
||||
4. Rollback steps
|
||||
5. `memory-bank/change-log.md` entry content
|
||||
```
|
||||
|
||||
## Prompt B — Slice B1.2 (document signed-flow migration)
|
||||
|
||||
```
|
||||
Act as a senior architect + senior software engineer working in PEDW FrontEnd.
|
||||
|
||||
Before any analysis or code changes:
|
||||
1) Ask for the Azure DevOps work item ID (required).
|
||||
2) Create a new branch from `origin/SIPS-Development` prefixed with that ID (e.g. `TASK67890-document-signed-migration`).
|
||||
3) Confirm branch name and only then proceed.
|
||||
|
||||
Goal:
|
||||
Implement Slice B1.2 only: migrate remaining signed flows in `documentDirectService` to shared signed-request helper(s) with no behavior change.
|
||||
|
||||
Exact scope:
|
||||
- Update `actions/services/documentDirectService.js` signed GET/POST/DELETE paths to use shared signed helper(s).
|
||||
- Preserve hash generation, headers, methods, and catch-path behavior.
|
||||
- Do not modify unrelated services.
|
||||
|
||||
Mandatory context to read before coding:
|
||||
- `.clinerules/default-rules.md`
|
||||
- `GUARDRAILS.md`
|
||||
- `context/architecture.md`
|
||||
- `context/current-state-scorecard.md`
|
||||
- `context/next-work-plan-sequence-b.md`
|
||||
- `context/test-coverage-map.md`
|
||||
- latest relevant `memory-bank/change-log.md` entries
|
||||
|
||||
Required output before edits:
|
||||
1. Scope and non-goals
|
||||
2. Risks and containment
|
||||
3. Files to touch
|
||||
4. Acceptance criteria
|
||||
5. Validation checklist
|
||||
|
||||
Validation minimum:
|
||||
- `npm run lint`
|
||||
- `node tests/phase22/index.test.cjs`
|
||||
- `node tests/phase7/service-behaviour.test.cjs`
|
||||
|
||||
Completion output:
|
||||
1. Files changed
|
||||
2. Behavior parity statement
|
||||
3. Validation evidence
|
||||
4. Rollback steps
|
||||
5. `memory-bank/change-log.md` entry
|
||||
```
|
||||
|
||||
## Prompt C — Slice B2.1 (auth logging hardening)
|
||||
|
||||
```
|
||||
Act as a senior architect + senior software engineer working in PEDW FrontEnd.
|
||||
|
||||
Before any analysis or code changes:
|
||||
1) Ask for the Azure DevOps work item ID (required).
|
||||
2) Create a new branch from `origin/SIPS-Development` prefixed with that ID (e.g. `US12345-auth-logging-hardening`).
|
||||
3) Confirm branch name and only then proceed.
|
||||
|
||||
Goal:
|
||||
Implement Slice B2.1 only: harden logging in `pages/api/auth/[...nextauth].js` using redacted structured logging with no behavior change.
|
||||
|
||||
Exact scope:
|
||||
- Replace sensitive/verbose direct logs in auth route with structured logger usage.
|
||||
- Do not alter auth/session/redirect functional behavior.
|
||||
|
||||
Mandatory context to read before coding:
|
||||
- `.clinerules/default-rules.md`
|
||||
- `GUARDRAILS.md`
|
||||
- `context/architecture.md`
|
||||
- `context/next-work-plan-sequence-b.md`
|
||||
- `memory-bank/open-questions.md` (Q-001)
|
||||
|
||||
Validation minimum:
|
||||
- `npm run lint`
|
||||
- `node tests/phase22/auth-redirect-safety.test.cjs`
|
||||
- targeted manual negative-path check for auth error logging paths
|
||||
|
||||
Completion output must include:
|
||||
1. Redaction policy applied (fields excluded)
|
||||
2. Files changed
|
||||
3. Behavior parity statement
|
||||
4. Validation evidence
|
||||
5. Rollback plan
|
||||
6. `memory-bank/change-log.md` update text
|
||||
```
|
||||
|
||||
## Prompt D — Slice B2.2 (file/email logging hardening cluster)
|
||||
|
||||
```
|
||||
Act as a senior architect + senior software engineer working in PEDW FrontEnd.
|
||||
|
||||
Before any analysis or code changes:
|
||||
1) Ask for the Azure DevOps work item ID (required).
|
||||
2) Create a new branch from `origin/SIPS-Development` prefixed with that ID (e.g. `TASK67890-file-email-logging-hardening`).
|
||||
3) Confirm branch name and only then proceed.
|
||||
|
||||
Goal:
|
||||
Implement Slice B2.2 only: harden logging in one bounded file/email route cluster using redacted structured logs.
|
||||
|
||||
Exact scope:
|
||||
- Choose a small cluster in `pages/api/file/**` and/or `pages/api/email/**`.
|
||||
- Replace risky direct logs with structured redacted logging.
|
||||
- Preserve endpoint contracts and negative-path semantics.
|
||||
|
||||
Validation minimum:
|
||||
- `npm run lint`
|
||||
- targeted tests for changed handlers
|
||||
- explicit negative-path check(s) for unauthorized/invalid input behavior
|
||||
|
||||
Completion output:
|
||||
1. Cluster chosen and why
|
||||
2. Files changed
|
||||
3. Redaction fields/policy applied
|
||||
4. Validation evidence
|
||||
5. Rollback steps
|
||||
6. `memory-bank/change-log.md` update text
|
||||
```
|
||||
|
||||
## Best use
|
||||
|
||||
- Run Sequence B slices as independent, reviewable commits
|
||||
- Start a fresh chat and execute one prompt at a time
|
||||
- Keep each slice bounded with explicit rollback
|
||||
+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).
|
||||
@@ -51,4 +51,33 @@
|
||||
- Current baseline runtime for this debt plan is the standard Next runtime path (`npm start`).
|
||||
- Runtime canonicalization is therefore removed from the active prioritized debt list unless deployment evidence changes.
|
||||
|
||||
## 5) Progress snapshot against architecture/debt review (2026-03-25)
|
||||
|
||||
Cross-referenced with:
|
||||
|
||||
- `context/architecture.md` (status + execution sequence)
|
||||
- `memory-bank/architect-review.md`
|
||||
|
||||
Status by debt item:
|
||||
|
||||
1. **Monolithic `actions/index.js`** -> **in progress**
|
||||
- Significant modular extraction completed (shared clients and route helpers), but full domain split remains open.
|
||||
2. **Inconsistent API contracts** -> **major progress**
|
||||
- Broad endpoint hardening and contract normalization completed across many route clusters.
|
||||
3. **Sensitive/verbose logging** -> **partial progress**
|
||||
- Relay path improved; broader auth/email/file redaction standardization still pending.
|
||||
4. **Endpoint sprawl/duplication** -> **major progress**
|
||||
- Shared relay/request helpers reduced repeated route logic; long-tail cleanup remains.
|
||||
5. **i18n rewrite complexity** -> **improving**
|
||||
- Targeted EN/CY rewrite parity automation now exists; CI enforcement still pending.
|
||||
6. **Sparse high-risk tests** -> **major progress**
|
||||
- Focused automation now covers auth redirect safety, signed-delete/upload negative paths, and EN/CY parity checks.
|
||||
7. **Legacy/stale patterns** -> **partial progress**
|
||||
- Multiple cleanup slices completed; still an ongoing hygiene lane.
|
||||
|
||||
Immediate recommended next lane (aligned to architecture Sequence B):
|
||||
|
||||
- Consolidate signed-request patterns behind a focused helper.
|
||||
- Apply broader logging hardening in auth/file/email/account-sensitive paths.
|
||||
|
||||
If you want, I can convert this into a sprint-ready debt register (ID, owner, effort, risk reduction, target milestone).
|
||||
@@ -112,3 +112,61 @@ Related:
|
||||
|
||||
- `context/runbook.md`
|
||||
- `memory-bank/change-log.md` (CL-032)
|
||||
|
||||
---
|
||||
|
||||
### D-004: Runtime canonicalization decision needed (`server.js` vs `server/server.js`)
|
||||
|
||||
date: 2026-03-25
|
||||
author: Cline
|
||||
scope: runtime startup path, scripts, runbook documentation
|
||||
type: decision
|
||||
rationale: Architecture/debt review identifies persistent ambiguity from dual server entrypoints, increasing operational drift risk.
|
||||
impact: Affects release reliability, troubleshooting clarity, onboarding consistency, and change safety for runtime-affecting work.
|
||||
status: proposed
|
||||
|
||||
Decision:
|
||||
|
||||
- Adopt one explicit canonical runtime startup path for dev/test/prod and document it in runbook + scripts.
|
||||
- Mark the non-canonical server entrypoint as deprecated (or remove when safe) with rollback instructions.
|
||||
|
||||
Consequences:
|
||||
|
||||
- Reduces deployment and incident-response ambiguity.
|
||||
- Requires coordinated validation across environments before deprecating the alternate path.
|
||||
|
||||
Related:
|
||||
|
||||
- `memory-bank/architect-review.md`
|
||||
- `context/architecture.md`
|
||||
- `context/runbook.md`
|
||||
|
||||
---
|
||||
|
||||
### D-005: Introduce CI baseline checks for high-risk parity/coverage gates
|
||||
|
||||
date: 2026-03-25
|
||||
author: Cline
|
||||
scope: CI policy for architecture/debt hardening lanes
|
||||
type: decision
|
||||
rationale: High-value focused tests now exist but are not yet fully institutionalized as explicit baseline gates for parity-sensitive change safety.
|
||||
impact: Improves release confidence and reduces regression drift in auth/i18n/high-risk integration paths.
|
||||
status: proposed
|
||||
|
||||
Decision:
|
||||
|
||||
- Add baseline CI checks for:
|
||||
- `npm run lint`
|
||||
- phase22 aggregate high-risk checks (`tests/phase22/index.test.cjs`)
|
||||
- EN/CY parity validation checks (initial rewrite parity scope)
|
||||
|
||||
Consequences:
|
||||
|
||||
- Tightens merge discipline for high-risk changes.
|
||||
- May require staged rollout to avoid pipeline disruption while stabilizing flaky areas.
|
||||
|
||||
Related:
|
||||
|
||||
- `context/test-coverage-map.md`
|
||||
- `context/current-state-scorecard.md`
|
||||
- `memory-bank/open-questions.md` (Q-002)
|
||||
|
||||
@@ -29,13 +29,20 @@ impact: Potential privacy/security exposure via operational logs.
|
||||
status: open
|
||||
|
||||
Question:
|
||||
What mandatory redaction and logging policy should be enforced for auth/email/document flows?
|
||||
What mandatory redaction and structured logging policy should be enforced for auth/email/document flows (fields blocked, allowed metadata, and incident correlation expectations)?
|
||||
|
||||
Needed from:
|
||||
Security lead + application owner
|
||||
|
||||
Decision deadline:
|
||||
Before next auth/notification release
|
||||
Before Sequence B Workstream B2 rollout
|
||||
|
||||
Current context:
|
||||
|
||||
- Relay logging policy has already been hardened in middleware, but auth/email/file routes still have uneven logging style.
|
||||
- Reference planning docs:
|
||||
- `context/next-work-plan-sequence-b.md`
|
||||
- `context/current-state-scorecard.md`
|
||||
|
||||
### Q-002: Test Strategy Baseline for Sparse `tests/`
|
||||
|
||||
@@ -48,10 +55,36 @@ impact: Increased regression risk and slower release confidence.
|
||||
status: open
|
||||
|
||||
Question:
|
||||
What minimum automated coverage should be required per change type (feature, bug fix, high-risk integration)?
|
||||
What minimum automated coverage should be required per change type (feature, bug fix, high-risk integration), and which suites become mandatory CI gates?
|
||||
|
||||
Needed from:
|
||||
Engineering lead + QA
|
||||
|
||||
Decision deadline:
|
||||
Before next major feature cycle
|
||||
Before enabling Sequence C CI parity gate rollout
|
||||
|
||||
Current context:
|
||||
|
||||
- Focused high-risk automation exists in phase21/phase22 (auth redirect, i18n route parity, relay hardening, endpoint contract slices).
|
||||
- A formal CI baseline decision is still needed to institutionalize these checks.
|
||||
|
||||
---
|
||||
|
||||
### Q-003: Runtime canonical startup path selection
|
||||
|
||||
date: 2026-03-25
|
||||
author: Cline
|
||||
scope: runtime startup path and operational documentation
|
||||
type: question
|
||||
rationale: Dual server entrypoints (`server.js` and `server/server.js`) remain a known architecture ambiguity in review artifacts.
|
||||
impact: Operational ambiguity can increase deployment and incident-response risk.
|
||||
status: open
|
||||
|
||||
Question:
|
||||
Which startup path is canonical for dev/test/prod, and what is the deprecation plan for the non-canonical entrypoint?
|
||||
|
||||
Needed from:
|
||||
Technical lead + DevOps owner
|
||||
|
||||
Decision deadline:
|
||||
Before runtime-affecting refactor or next deployment process update
|
||||
|
||||
Reference in New Issue
Block a user