Skip to content

docs(planning): reconcile AutoAudit product docs with engineering plan + board #156

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
anmolg1997 wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs(planning): reconcile AutoAudit product docs with engineering plan + board #156

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
116 changes: 116 additions & 0 deletions planning/RECONCILIATION.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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).
Loading