diff --git a/planning/RECONCILIATION.md b/planning/RECONCILIATION.md new file mode 100644 index 0000000..51e3dc2 --- /dev/null +++ b/planning/RECONCILIATION.md @@ -0,0 +1,116 @@ +# Product ↔ Engineering Reconciliation + +> **Date:** 2026-06-18 +> **Purpose:** Reconcile Akhilesh's product docs (`planning/VISION.md`, `MVP.md`, `ROADMAP.md`, `JOURNEY_MAPS.md`, on the `product-planning` branch) with the engineering plan already in flight (the GitHub Projects board "BMR Compliance Intelligence — Enterprise MVP", project #9; the merged WS-A data foundation and WS-B identity). +> **Decision basis:** Akhilesh — "redefine the [board] items based on these docs … some of them, not the ones that are foundation/technical." +> **This doc says:** what the product reframe changes, what it does **not** (the foundation we keep), the concrete board change-set, the reconciliations we must make, and the few decisions still open. + +--- + +## 1. The reframe in one paragraph + +The product is repositioned from **"BMR Compliance Intelligence"** (a document-compliance engine) to **"AutoAudit AI"** — an AI-native QMS with a **10-stage audit lifecycle**. Our entire current codebase is now positioned as the **"Document Intelligence Engine"** (Stages 2–5 for individual documents). The **MVP = Stages 0–5** wraps that engine in a real audit product with net-new domain entities (Profile, Audit Event, Work Item, Evidence, Finding), 9 screens, 4 roles, My-Work queues, a posture Dashboard, and in-app notifications. Two go-to-market journeys (A: AI layer on an existing QMS; B: standalone QMS = the MVP demo target) and three deployment models (on-prem air-gapped / hybrid / SaaS). + +**Consequence:** none of our merged foundation is wasted or "redefined" — it is exactly the substrate the product sits on. What gets redefined is the **product/feature** layer (board workstreams F and G), plus a large body of **net-new product work** that isn't on the board at all yet. + +--- + +## 2. Prototype/foundation → product mapping + +Per MVP.md §9 ("What the Prototype Provides"): + +| Our asset | Product role | Status | +|---|---|---| +| OCR pipeline (Azure DI / Marker+Docling / Datalab) | Stage 2 evidence ingestion | **Carries over as-is** | +| Compliance engine (ALCOA+, GMP, SOP, checklist, `agentic_audit`) | Stage 3 automated analysis | **Carries over**; rules sourced from a **Profile** instead of global config | +| HITL split-pane review | Stage 4 human review | **Carries over**; output must drive **Work Item** status, not document status | +| Compliance findings output | Stage 5 finding data | **Carries over**; a structured **Finding** entity sits on top | +| WS-A: Postgres + arq queue + storage port + config resolver | Data/job/storage substrate for all entities | **Done (merged)** — underpins Profile/AuditEvent/WorkItem/Finding, runs Stage-3 analysis, stores evidence | +| WS-A: Tenant→Site→Product hierarchy + tenant-scoped boundary | Multi-tenancy foundation | **Done** — answers MVP Open Q1 (see §4) | +| WS-B: federated OIDC + RBAC + audit-actor | Auth/authz substrate | **Done**; **roles need realignment** (see §4) — answers MVP Open Q2 | +| audit-rule-author skill + agentic_audit guide (PR #155) | Stage 0 Profile rule authoring + Stage 3 agentic checks | **Landing (PR #155)** — closes the "waiting on Akhilesh's agentic spec" item | + +**Net-new for MVP (not in the prototype, not on the board):** Profile Builder UI + model (Stage 0), Audit Planner + Audit Event + Work Item coordination (Stage 1), Evidence↔Work-Item wiring (Stage 2), Finding entities (Stage 5), My-Work queues, posture Dashboard, in-app notifications, the 4-role product model. + +--- + +## 3. Board disposition (project #9) + +Akhilesh's rule: redefine product items, keep foundation/technical. Applying it: + +| Item | Disposition | Action | +|---|---|---| +| **A1** Postgres system of record | KEEP — **Done** | Mark Done (PR #150) | +| **A2** Durable job queue (arq) | KEEP — **Done** | Mark Done (PR #152) | +| **A3** Storage port (MinIO/S3, tenant-prefixed) | KEEP — **Done** | Mark Done (PR #151) | +| **A4** SoC refactor (split God objects) | KEEP | Pending — this is the "adapter to wire engine to Work Items" the ROADMAP flags as Sprint-3 risk | +| **A5** Config & feature flags (resolver) | KEEP — **Done** (resolver) | Mark Done (PR #151); live-load-path integration still pending | +| **B1** Real auth (OIDC) | KEEP — **Done** | Mark Done (PR #154); **reconcile** local/Keycloak path for SaaS demo (§4) | +| **B2** RBAC roles | KEEP — **Done but RECONCILE** | Roles change from admin/qc_auditor/team_lead/viewer → the 4 product roles + Document-Owner upload perm (§4) | +| **B3** Multi-tenancy isolation | KEEP | Foundation; design-for-isolation done, enforcement deferred | +| **B4** Security hardening | KEEP | Foundation | +| **C1** Immutable audit trail (Part 11) | KEEP | = our deferred WS-C; first audit-event writer shipped in WS-B | +| **C2** Electronic signatures | KEEP — **ELEVATE** | Now required for Profile approval, Work Item approval, Finding ack, CAPA closure (VISION §11) | +| **C3–C5** AI-inference audit / validation pack / retention+export | KEEP | C5 export feeds Stage 8 Audit Pack | +| **D1–D5** LLM-Ops (gateway, Langfuse, evals, guardrails, model-retirement) | KEEP | Powers the per-stage AI agents | +| **E1–E4** CI/CD + deploy (compose, CD, K8s/air-gapped, staging/DR) | KEEP | E3 = the 3 deployment models | +| **F1** Frontend hardening | REDEFINE | Folds into Phase-0 stabilize + Sprint-5 polish | +| **F2** "Review by exception" UX | REDEFINE | → Stage 4 Reviewer queue (risk-sorted) + Dashboard | +| **F3** Self-service config UI | REDEFINE/DEFER | → Phase-2 "customer self-service Profile management" | +| **F4** Admin UI: users/roles/tenants | REDEFINE | This is the product-definition anchor Akhilesh used; broadens into the MVP product | +| **G1–G3** Agentic audit v2 | REDEFINE | "Agentic audit v2" is now concretely the **8 named stage-agents**; G2's spec = the landed agentic_audit guide + VISION §9 | +| **NET-NEW: WS-P Product MVP** | **ADD** | Stage 0–5 epics + 9 screens + 4-role multi-user + Dashboard + notifications (the bulk of the MVP) | + +--- + +## 4. Reconciliations we must make + +1. **Roles (real change).** WS-B ships `admin / qc_auditor / team_lead / viewer`. Product wants `Team Lead / Reviewer / Document Owner / Site Head` (6 at maturity, +CAPA Owner, +Inspector). Mapping: team_lead→Team Lead, qc_auditor→Reviewer, admin→Site Head (approver) + platform-admin. **Document Owner is net-new** and needs an `EVIDENCE_UPLOAD/SUBMIT` permission `viewer` does not have. A focused WS-B follow-up (role enum + permission + group-map), not a rebuild. +2. **Auth strategy — our foundation answers MVP Open Q2.** VISION §13.3 itself says on-prem needs a self-hosted IdP (Keycloak/authentik) and hybrid/SaaS can use a managed OIDC provider — exactly our WS-B (federated OIDC + Keycloak, already in compose). The docs' "NextAuth vs Clerk, username/password" can be closed: Keycloak gives username/password for the SaaS demo without contradicting the architecture. **Recommend Akhilesh marks Open Q2 resolved.** +3. **Multi-tenancy — our foundation answers MVP Open Q1.** WS-A's tenant-scoped boundary + on-prem instance-per-tenant matches the docs' lean toward separate instances. **Recommend Open Q1 resolved** (design-for-isolation now; enforcement when SaaS multi-customer lands). +4. **Naming collisions (fix before building product entities).** Product **"Audit Event"** vs our `AuditEventRow` (the 21 CFR audit *trail*) — different things, same name. Product **"Product Profile"** vs our `Product` hierarchy entity. Choose distinct names (e.g. product entity `AuditRun`/`audit_runs`; or rename the trail to `AuditTrailEvent`). +5. **Phase-0 already partly done.** PDF viewer = **fixed**. "BMR Runs missing `X-Actor-Id`" = **obsolete** (WS-B removed `X-Actor-Id`). Phase-0 shrinks to `/documents` page + Legibility HITL UI. +6. **E-signatures (C2) elevated.** Regulated approval actions now need a two-factor e-signature (VISION §11) — a foundation dependency for Stage-0/4/5 approvals. + +--- + +## 5. Open decisions (for Akhilesh / product) + +| # | Decision | Why it matters now | +|---|---|---| +| 1 | **Brand**: "AutoAudit AI" (docs) vs "BMR Compliance Intelligence" (current masthead/footer/board) | Renames the product, board, and UI brand; pick one before product UI work | +| 2 | **MVP demo target: SaaS vs on-prem** (ROADMAP Open Q6) | Drives the auth/tenancy path for the demo (managed OIDC + RLS vs Keycloak + instance) | +| 3 | **Reviewer assignment** (per-audit vs per-Work-Item; MVP Open Q4) | Shapes the Work Item model + queue logic | + +MVP Open Q1 (multi-tenancy) and Q2 (auth) are **already answered by our foundation** (§4.2–4.3) — recommend closing them. + +--- + +## 6. Recommended re-sequencing + +Adopt the product roadmap's phasing for near-term sequencing, threading the foundation items as dependencies: + +- **Phase 0 — Stabilize:** `/documents` page, Legibility HITL UI. (PDF viewer + X-Actor-Id already resolved.) +- **Phase 1 — Build (Sprints 1–5):** Sprint 1 auth+4 roles+Profile (← **role realignment lands first**); Sprint 2 Audit Event + Work Items; Sprint 3 Evidence↔Work-Item + analysis wiring (← needs A4 adapter); Sprint 4 Review + Findings; Sprint 5 Dashboard + notifications + QA. +- **Foundation (A4, B-role-realign, C2, D, E)** runs as dependency tracks feeding the sprints. +- **Phase 2/3** absorb CAPA/Inspection/Learning + integrations + multi-site (board C/D/E/F-deferred items map here). + +The **frontend login slice** previously proposed is **Sprint 1** work — but the **role realignment must precede it** so the UI is built against the right role model. + +--- + +## 7. Proposed board change-set (ready to apply on confirmation) + +1. **Mark Done:** A1, A2, A3, A5, B1, B2 (link PRs #150/#151/#152/#154). +2. **Re-label / redefine:** F1→"Frontend hardening + Phase-0 polish"; F2→"Stage 4 Reviewer exception queue + Dashboard"; F3→"Self-service Profiles (Phase 2)"; F4→"Product MVP definition (Stages 0–5)"; G1–G3→the named stage-agents. +3. **Add WS-P (Product MVP)** epics: P0 Profile mgmt · P1 Audit Event+Work Items · P2 Evidence↔Work-Item · P3 per-WorkItem analysis+streaming · P4 Review→status+diff · P5 Finding entities · P6 My-Work queues · P7 Dashboard · P8 Notifications · P9 4-role multi-user (depends on B2 realign). +4. **Add reconciliation tasks:** "B2 role realignment to product roles + Document-Owner perm"; "Rename collision: product Audit Event vs AuditEventRow trail"; "C2 e-signatures for approvals". +5. **Close as resolved:** MVP Open Q1 (multi-tenancy) and Q2 (auth) — answered by WS-A/WS-B. + +--- + +## 8. Akhilesh's skill + the rest of evidence-synthesis + +- **audit-rule-author skill** — landing via **PR #155** (self-contained against main; main-compat fixes applied). Its `agentic_audit_guide.md` is the agentic-v2 authoring guidance we awaited. +- **Rest of `evidence-synthesis`** (~1,600 lines: rules/segmentation/report-renderer changes + evidence-synthesis tests) is a **separate feature**, not part of the skill, and keeps its own review (prior review flagged an evidence-wipe concern). Recommend a dedicated PR for it, decoupled from the skill. +- **`product-planning`** (these docs) should merge to main so the product source-of-truth is canonical (this RECONCILIATION.md references it).