CDA roadmap: resolve dirty changes and resume development
Preserve the unfinished work, decide which changes belong in OMP, and establish a tested baseline before completing programme workflows and migration. This plan adds a concrete recovery phase to the earlier programme roadmap.
Start with a recoverable baseline
Use omp-api and omp-client as the continuation candidates. Keep the latest orphan-database as the reference for legacy behaviour. The immediate job is to account for every local change and separate useful business fixes, incomplete experiments, local settings, and generated audit files.
What is complete today
Both project reports have been read. All ten repository directories have been checked. The three working trees with application changes match the audit's warning. Their staged diffs are empty. The inventory below reflects local files on 12 September 2026; builds, databases, remote branches, and production behaviour have not been verified.
The first implementation milestone is deliberately small. Preserve the originals, review the dirty changes in isolated copies, and produce a tested OMP baseline with a written disposition for every change. Feature expansion follows that gate.
This roadmap does not settle current programme policy. Donor access, social-worker responsibilities, finance approval, report meaning, and legacy retirement need decisions from the people responsible for those operations.
The dirty changes, verified
Working tree | Local state | What it means |
|---|---|---|
omp-api at 1b75249 | One modified tracked file. Three untracked application artifacts, plus the generated audit directory. | Academic-result existence helper, a district GraphQL query, a reporting experiment, and a SQL session file. |
Latest orphan-database at df7ea1d | Six modified tracked files, plus the generated audit directory. | Geography registration and restrictions, upload filename handling, local ports, and formatting. |
Earlier orphan-database at 0191323 | Three modified tracked files, plus the generated audit directory. | Start/dev scripts, Prisma package and lockfile changes, and weakened session-cookie settings. |
omp-client at 9565dff | Generated audit directory only. | No application diff found. Use this as the frontend starting snapshot. |
Four other distinct historical snapshots | Generated audit directory only. | Preserve their historical role. They do not need separate feature development. |
Two duplicate directories | Clean working trees. | Archive decisions still require backup and uniqueness verification. |
Generated files are a separate category
The eight distinct repository snapshots each have an untracked .understand-anything directory. The earlier audit attributes the domain graphs to its analysis. Confirm the complete directory contents before deciding whether to keep them as documentation or exclude them from application work.
The detailed local inventory is DIRTY_CHANGE_INVENTORY.md in this project. It records exact paths and the evidence behind the proposed actions. No original application files were changed during this planning pass.
Milestone 0. Preserve and classify
Owner role: technical lead. Start here. Product questions can be gathered while preservation proceeds.
Capture each repository's HEAD, branches, staged and unstaged status, and untracked file list. Record the runtime manifests and lockfiles without copying credentials into the roadmap.
Create recoverable Git bundles and separate binary patches for staged and unstaged changes. Copy the changed and untracked files with their relative paths. Include the SQL session file and generated artifacts in the private recovery set. A Git bundle alone does not preserve working-tree changes.
Check ignored files for configuration, uploads, or other unique assets. Record them in a private inventory and preserve the required items separately. Treat credentials and programme records as private material.
Verify the recovery set in a temporary checkout. Reapply the patches, restore the copied files, and compare the recovered file hashes with the source. Keep a copy outside the original repositories before cleanup.
Create isolated OMP working copies for implementation. Do not rely on a clean worktree to carry over untracked experiments. Reapply only the changes selected for review.
Classify each change as keep and repair, preserve as an experiment, replace with a new implementation, or exclude from the application baseline. Record the reason, destination, reviewer, and verification for each.
Gate 0
The recovery set can reconstruct all three dirty trees. Every application change and untracked artifact has a recorded destination. No original change is silently discarded. Runtime work uses isolated copies, with the originals preserved.
Milestone 1. Resolve the changes in reviewable pieces
Work item | Proposed treatment | Proof required |
|---|---|---|
D1. Academic-result existence helper | Keep the intent and repair it. The new assertExists uses !!this.findOne, which tests a promise instead of the database result. Match the neighbouring service's awaited lookup and missing-record exception contract after checking callers. | Tests cover an existing record, missing record, and database failure. Missing records cannot pass the check. Verify every caller awaits it. |
D2. Reporting experiment | Preserve the experiment separately, then replace its timer-based counting with awaited operations and deterministic fixtures if the report is retained. The file is named as an e2e test but has no test assertions, calls a local API when loaded, and prints counts after a one-second timer. | Ordinary test discovery cannot trigger the experiment. Tests run without an existing local API. Delayed responses still produce correct totals, and rejected requests fail visibly. |
D3. District query and SQL session | Retain the GraphQL query only with its intended report or a labelled example. Inspect the SQL privately for useful queries, credentials, data, and mutations before moving anything into maintained code. | The SQL file has a documented disposition and has not been executed against an unknown database. Approved examples contain synthetic data and belong to a defined report contract. |
D4. Geography registration | Port useful behaviour into OMP after comparing current forms and API rules. The legacy edits change region/zone/district selection, refresh options after creation, and make the village district required. | Switching parent selections clears stale descendants. Cancelling and reopening works. Duplicate names cannot select the wrong ID. The API rejects invalid parent-child relationships. |
D5. Geography reassignment and project dates | Decide the rule before implementation. The GraphQL diff deprecates district reassignment arguments; a deprecation label does not enforce a restriction. The UI also removes project start-date limits. | Direct API calls enforce the agreed reassignment policy. Programme reviewers accept historical and future project-date cases. |
D6. Upload filenames | Replace the legacy filename helper with a reviewed storage rule in OMP if needed. The dirty helper replaces characters and truncates names; preserve original display names separately. | Long names, Unicode, duplicate names, extension preservation, and invalid uploads have defined outcomes. Stored attachment references remain valid. |
D7. Local ports and formatting | Keep local port choices in environment configuration. Exclude whitespace and formatting-only hunks from functional patches after preservation. | Frontend endpoint, API listener, and allowed development origins agree. The change can be reviewed without unrelated formatting. |
D8. Old startup and dependency edits | Preserve as historical evidence. Replace any still-useful startup convention in the maintained OMP deployment. Do not transplant the old Prisma version bump into OMP. | Lockfile and manifest agree in the chosen baseline. Documented startup works in a clean environment. |
D9. Old session-cookie changes | Retire the insecure override from future code. The older clone sets httpOnly and secure to false. Keep the original diff only in the recovery archive. | The retained application's production session configuration has the required cookie protections and works behind its actual deployment proxy. |
D10. Generated audit directories | Keep useful domain graphs with supporting documentation or exclude them from application tracking through a deliberate repository decision. | No generated audit artifact is mistaken for an unfinished product feature. The originals remain recoverable. |
Order the review as D1 to D3, D4 to D7, then D8 to D10. Keep commits separated by behaviour. The legacy fixes are requirements evidence for OMP, not an instruction to merge unrelated repository histories.
Gate 1
All ten items have an accepted disposition. Retained OMP changes pass their focused checks. Deferred experiments have a location and owner. The isolated continuation baseline has no unexplained changes; the preserved originals may remain dirty.
Milestone 2. Prove the baseline and close access gaps
Owner role: technical lead, with programme input on permissions. Depends on Gate 0 and the relevant Milestone 1 decisions.
Install from the selected lockfiles in isolated copies. Record the actual Node and package-manager requirements. Run builds and existing tests, then record failures as baseline issues. The OMP lint script currently applies fixes, so use a check-only invocation while measuring the baseline.
Use a disposable database and synthetic fixtures. Review test and startup scripts before running them. Establish login, intake, geography, education, support plans, payments, and upload smoke checks.
Address the audit's known frontend auth condition and missing layout. Confirm the current code before repairing them. Decide the Nuxt/Vue maintenance path from a small compatibility exercise rather than combining a full upgrade with every parity fix.
Define and enforce a server role/action/record-scope matrix. Cover self-selected signup roles, cross-donor and cross-territory access, exports, assignments, deletions, and account maintenance.
Remove fallback secrets from the release configuration. Define account recovery and session handling. Add dated actor history for sensitive case, assignment, sponsorship, and financial changes.
Gate 2
A new checkout starts from documented steps with synthetic data. Builds and required checks pass, or each nonblocking inherited failure has a written reason and owner. Unauthorized reads and writes fail at the API. No access or session blocker remains for the chosen release scope.
Milestones 3 to 6. Finish the programme workflow
Milestone and dependency | Deliverable and role owner | Completion gate |
|---|---|---|
3. Case operations and product decisions. After Gate 2. | Programme owner and technical lead agree the retained roles, then finish intake, geography, assignment, education, health, documents, photos, and letters. Resolve validation and duplicate-handling rules. | Representative staff complete intake, correction, reassignment, and an education or field update. Required validations and record permissions pass. |
4. Sponsorship and finance. After agreed roles and case rules. | Programme and finance owners define donor selection, plans, transition dates/reasons, expiry, receipts, exchange rates, fee basis, precision, rounding, allocation, approval, and corrections. | One complete registration-to-sponsorship-to-payment cycle reconciles. Tests cover retries, donor mismatch, partial funds, rejected approval, reversals, and invalid transitions. |
5. Reports and migration. Contracts start during Milestone 3; acceptance follows stable workflow rules. | Programme, finance, and data owners accept Payment History, Status, and Education contracts. Technical lead implements reports and a repeatable legacy-ID-to-OMP-ID importer. | Report fixtures match the approved layouts and totals. Two migration rehearsals reconcile records, relationships, money, dated history, and attachments. No unexplained difference remains. |
6. Pilot, cutover, and archive. After Gate 5 and release checks. | Operational reviewers complete a bounded programme cycle. Technical and data owners rehearse final backup, edit freeze, import, reconciliation, switch, and rollback. | Owners accept pilot results and a tested rollback. Support and backup ownership are assigned. Archive restoration and unique-data checks precede duplicate removal. |
Report contracts to settle early
Payment History needs orphan, donor, and project views with the specified currency, fee, and total columns. Status needs a decision between termination-only output and general status history. Education needs location, donor, and project groupings plus an academic-period rule and repeat-count definition. The workbook does not settle filter semantics or permissions.
Start read-only data discovery and report examples alongside baseline work. Confirm whether the authoritative database and document store survive before schema migration or archival decisions. If no usable source survives, replace import work with a documented re-entry and reconciliation plan.
Prefer application-native outputs for the three fixed report families as a proposal for review. Defer exploratory analytics until those contracts pass. Do not interpret the unfinished count experiment as delivery of the required reports.
Legacy capabilities need current decisions
These are proposed dispositions, not approved retirements. Port preserves a business capability in OMP. Replace preserves its purpose through an agreed alternative. Retire removes it from maintained scope while keeping required historical records.
Capability | Proposed disposition | Decision owner and deadline |
|---|---|---|
Donor and Social Worker tasks | Port the required tasks. A staff-assisted replacement is an option if direct access is no longer needed. | Programme owner, before Milestone 3 scope is accepted. |
Sponsorship transitions and history | Port with allowed actors, effective dates, and reasons. | Programme and finance owners, before Milestone 4. |
Financial records and IGA records/photos | Replace overlapping finance records with the agreed model. Decide port or retire for active IGA work after usage review; retain its history either way. | Programme, finance, and data owners, before finance and migration mapping. |
Project and daily activities | Propose port if still required for the operating cycle. Otherwise record an explicit retire decision before excluding them. | Programme owner, before pilot scope. |
Account-maintenance approvals | Replace with controlled account recovery and separately governed payment-detail changes. | Programme and technical owners, before Gate 2. |
Current/latest condition snapshots | Replace with dated history and an explicit current-record rule. | Programme and data owners, before reports and migration. |
Payment, status, and education reports | Port the agreed workbook contracts and required exports. | Programme and finance owners, define during Milestone 3. |
Other historical suggestions and custom analytics | Defer pending a current requirement. Decide replace or retire individually when reviewed. | Programme owner, before adding any item to the release backlog. |
Trello Done labels, checklist counts, and historical suggestions do not establish present scope. If a decision depends on comment, checklist, or attachment content absent from the dumps, inspect that specific card in the signed-in board before accepting the requirement.
The next work package and planning limits
Next package A: verified recovery copies, repository inventory, and a change-disposition register. Deliver Gate 0 before edits.
Next package B: repair the academic-result helper and separate the report experiment in the isolated OMP backend. Deliver focused results for D1 to D3.
Next package C: translate the legacy geography and upload changes into OMP acceptance cases. Resolve D4 to D10 and complete Gate 1.
Next package D: establish the repeatable runtime and permission baseline. Turn the later milestones into implementation issues with an owner, dependency, evidence, and completion example.
Assign named people to the owner roles before scheduling acceptance work. Estimate Milestones 0 and 1 after the recovery inventory, and estimate the rest after the running baseline and data discovery. Calendar commitments now would hide the largest unknowns.
Evidence used: ORPHAN_PRODUCT_CHAIN_REPORT.md for lineage and capability gaps; TRELLO_BOARD_CONTEXT.md for historical intent and the workbook summary; fresh local Git status and selected diffs for the dirty-change inventory. The report workbook and live Trello comments were not re-inspected for this planning pass.
No dependency installation, build, application test run, SQL execution, production inspection, migration, or source cleanup was performed for this roadmap. The verification completed here is a read-only repository review and document validation.