inboxos-v1/docs/roadmap.md

InboxOS - Strategic Roadmap (docs/roadmap.md)

TL;DR — InboxOS — self-hosted personal ERP/CRM pipeline. Prompts-as-code, Gitea Actions, NocoDB, Ollama, SeaweedFS, Papra. This file explains how to stand it up and who to contact; the machinery detail stays lower under Details.

Author/maintainer (content): CPO — sole author of milestones, sequencing, and per-MINOR requirements. Author/maintainer (governance): SAA — owns the MAJOR Umbrella binding, the ## MAJOR scope declaration, the ## MINOR release list, and the Pillar I Gate PRs that bind this Roadmap to the Gitea hierarchy. Project: InboxOS (/INB/projects/inboxos) Source of truth: this document on main + the MAJOR v1 Initiative umbrella Issue in the Gitea repo. They MUST stay in lockstep; the umbrella is the audit chain anchor.

This is the single source of truth for when InboxOS capabilities ship and in what order. The CPO writes the timeline. The external ciagent software development harness builds against it. The CTO validates each release against it.

The CTO may read this document. The CTO may not edit it. The CPO may not edit .ciagent/. The SAA owns the ## MAJOR scope / ## MINOR release list headings and the bound umbrella Issue, and may update them only through a Pillar I Gate PR that the CPO reviews and merges.

MAJOR scope

This Roadmap represents the complete delivery of v1.x (MAJOR v1) of InboxOS. v1 is the self-hosted personal ERP/CRM pipeline product. v1 ships in MINOR releases; the active MINOR at any point in time is the one bound to the current Gitea Milestone. The MAJOR ends when a v2.x Strategic Roadmap is approved through a fresh Pillar I Gate; the v1 Roadmap is archived (never deleted) at that point.

The active v1 MAJOR Initiative umbrella Issue in Gitea is the single audit anchor for the v1 line. All v1 Initiatives, Epics, and PRs MUST trace back to it.

MAJOR Umbrella

Bound to the MAJOR Initiative umbrella Issue in Gitea. The umbrella carries:

• The label major/v1.
• A blockedBy link to the Pillar I Gate PR/Issue that approved this revision.
• Every Initiative for v1 as a sub-issue, each itself with blockedBy the umbrella and a Milestone assignment from the ## MINOR release list below.

Umbrella binding: populated by the SAA on first Pillar I Gate passage; before that, the umbrella Issue does not exist and the binding is empty.

MINOR release list

The MINOR names below are used verbatim to name Gitea Milestones (SAA SOP §6.3, form vN.M - <descriptive name>). PATCH releases do not get their own Milestone; they roll up into the MINOR. Existing shipped/legacy MINORs are kept (non-breaking) and labeled major/v1 going forward.

• v1.0 - MVP Foundation — initial pipeline + idempotency + observability. Status: shipped.
• v1.1 - Beta Cohort — first operator-cohort onboarding. Status: shipped.
• v1.2 - Initial Pipeline Hardening — papra + imapclient + schema discipline. Status: shipped.
• v1.3 - Stable Cut — stable post-recovery cut. Status: shipped; release quarantined and recovered per INB-295 / inboxos#17. No further commits under this MINOR without a fresh Pillar I Gate round.
• v1.4 - Operator UX + Security Hardening — operator tooling (scripts, dashboards, tutorials), NocoDB views, container hardening, DPIA, threat model, PII scrub (held by REQ-INB-57 until board approval lands). Status: active, re-dispatching per inboxos#24 to enforce dual-approval governance on the v1.4.0 wave.
• v1.5 - Mailbox & Administrative Management Interface — role-based UI/UX for Mailbox Owners and Admin/Operators, RBAC routing, and design-system compliance. Status: Pillar I Gate passed (PR !108 merged by grimacing, 2026-06-10). Active; CTO handoff in progress.
• Backlog — approved v1 work not yet scheduled into a MINOR. Status: open.

The Gitea Milestones in the repo carry the title only form (v1.0-MVP, v1.1-Beta, v1.2-initial, v1.4) for historical reasons. The SAA will:

1. Create new Gitea Milestones in the canonical vN.M - <descriptive name> form for any new work under v1.4 + Backlog.
2. Keep the existing legacy Milestones intact and assign them the major/v1 label, so existing issue→Milestone links do not break.
3. Issue a follow-up PR (separate, with CPO approval) when legacy Milestones can be renamed to the canonical form without breaking issue history.

Goals (verbatim from intake)

Drawn from Gitea Issues authored by the CPO (the product owner) and the CTO (technical intake). Verbatim sources are linked; the SAA does not paraphrase client goals.

1. InboxOS must ship a self-hosted personal ERP/CRM pipeline that ingests, classifies, and persists structured records from inbox sources (Gmail bridge, IMAP, papra writes, NocoDB).
   • Source: docs/requirements.md + docs/roadmap.md (CEO/board mandate INB-123).
2. Operator tooling must let a non-engineer run, observe, and recover the pipeline in 15 minutes.
   • Source: Gitea Issues inboxos#18 (v1.4 IDEATE, 15 UX candidates, REQ-INB-40..54), [inboxos#40..54] (operational scripts), [inboxos#50] (daily_digest), [inboxos#47] (operator tutorial).
3. Security and compliance must be product-grade — container hardening, DPIA, threat model, PII scrub before any external LLM call.
   • Source: Gitea Issues inboxos#18 (5 Security/PII candidates, REQ-INB-55..59), [inboxos#55..59] (container hardening, DPIA, threat model, pii_scrub).
4. Governance must be enforced at the PR-merge layer — dual approval (CPO + CTO), no force-merge, audit trail intact.
   • Source: Gitea Issue inboxos#24 (v1.4.0 re-dispatch, P0 governance defect per INB-328).
5. InboxOS must provide a polished, role-based Mailbox & Administrative Management Interface.
   • Source: Gitea intake issue REQ-001 (grimacing, 2026-06-10).
   • Open questions resolved: Super Admin view strictly separated; compliance/audit logs kept basic for the first round.

Initiatives

Initiatives are product-level strategic themes. Each Initiative is a sub-issue of the MAJOR Umbrella, assigned to a target MINOR Milestone, and decomposed into Epics (Pillar II work).

INTV-1 — Operator Self-Service Surface (v1.4)

• Traces to: Goal 2 (operator tooling).
• Success criteria: An operator can spin up a green-field InboxOS in 15 minutes (quickstart.sh, docs/quickstart.md), observe pipeline state via the NocoDB dashboard, and run recovery flows (explain_run, reclassify, replay) without engineering help.
• Out of scope: the scripts themselves (those are Pillar II/III work); the SAA only owns the Initiative + Epic tree.
• Epics (decomposed under this Initiative):
  • EPIC-INB-1.4-A: Quickstart + Operator Tutorial — quickstart.sh (REQ-INB-40), operator-tutorial.md (REQ-INB-53). Target: v1.4.
  • EPIC-INB-1.4-B: NocoDB Operator Views — curated views per module (REQ-INB-41). Target: v1.4.
  • EPIC-INB-1.4-C: Recovery & Explain Tools — explain_run.py (REQ-INB-42), reclassify.py (REQ-INB-44), replay.py (REQ-INB-45), daily_digest.py (REQ-INB-50). Target: v1.4.

INTV-2 — Product-Grade Security & Compliance (v1.4)

• Traces to: Goal 3 (security/compliance).
• Success criteria: InboxOS passes container hardening review, has a published DPIA, a published threat model (STRIDE per component), and a PII-scrub body that masks SSN/CC/IBAN/phone before any Ollama call.
• Out of scope: PII scrub (REQ-INB-57) implementation merge — held until board approval lands; this Initiative opens the Epic placeholder only.
• Epics:
  • EPIC-INB-1.4-D: Container Hardening — read-only rootfs, cap-drop, no-new-privileges (REQ-INB-55). Target: v1.4.
  • EPIC-INB-1.4-E: DPIA — GDPR Art. 35 (REQ-INB-58). Target: v1.4.
  • EPIC-INB-1.4-F: Threat Model — STRIDE per component (REQ-INB-59). Target: v1.4.
  • EPIC-INB-1.4-G: PII Scrub (held) — REQ-INB-57 implementation. Target: v1.4 conditional on board approval; not mergeable in current state per inboxos#24 §Acceptance criteria 4.

INTV-3 — Dual-Approval Governance (v1.4 carry-through)

• Traces to: Goal 4 (governance enforcement).
• Success criteria: A force-merged PR with 0 reviews (the defect behind INB-328) is no longer possible. The main branch-protection is set to require APPROVED reviews from cpo AND cto with dismiss_stale_approvals=true.
• Out of scope: the actual code-level implementation (admin-side repo config + branch protection); this Initiative is a process Initiative.
• Epics:
  • EPIC-INB-1.4-H: v1.4.0 Re-dispatch Under Dual Approval — the corrected re-dispatch wave per inboxos#24. Target: v1.4.

INTV-4 — Tech-Debt Lane (v1.0-MVP carry)

• Traces to: Goal 1 (core pipeline). Carries v1.3 tech-debt into the v1.0-MVP lane.
• Success criteria: REQ-INB-35c (.gitignore opencode.json shadow), REQ-INB-38 (apply_schemas.py --check), REQ-INB-39 (imapclient runtime-shim) all close with a passing CI and no regressions.
• Out of scope: v1.4.0 re-inclusion (per inboxos#24 §Acceptance criteria 4 — these are NOT in v1.4).
• Epics:
  • EPIC-INB-1.0-TD-1: papra_index --check test (REQ-INB-38). Target: v1.0-MVP.
  • EPIC-INB-1.0-TD-2: imapclient runtime-shim test (REQ-INB-39). Target: v1.0-MVP.
  • EPIC-INB-1.0-TD-3: .gitignore opencode.json un-shadow (REQ-INB-35c). Target: v1.0-MVP.

INTV-5 — Mailbox & Administrative Management Interface (v1.5)

• Traces to: Goal 5 (Mailbox & Administrative Management Interface).
• Success criteria:
  1. A dedicated Mailbox Owner View (dashboard) exists where owners can view a list of ingested emails, search/filter by metadata, and perform management actions (e.g., archive, mark as processed).
  2. A distinct Admin/Operator "Ops Console" exists providing high-level observability (ingestion rates, error logs, system latency) and administrative controls (user permission management, global configuration).
  3. Role-Based Access Control (RBAC) automatically routes users to the correct view based on permissions, preventing Mailbox Owners from accessing the Admin/Operator console.
  4. UI/UX polish: responsive layouts, intuitive navigation, clear visual feedback per the design system.
• Out of scope:
  • The actual email ingestion engine (backend logic) — already covered by existing pipeline work.
  • Integration with third-party email clients (Outlook/Gmail plugins).
  • Advanced analytics/reporting tools (custom PDF reports).
• Epics (decomposed under this Initiative):
  • EPIC-INB-1.5-A: Mailbox Owner Dashboard — UI + RBAC routing for the Mailbox Owner role (REQ-001 AC-1). Target: v1.5.
  • EPIC-INB-1.5-B: Admin/Operator Ops Console — observability dashboard + administrative controls (REQ-001 AC-2). Target: v1.5.
  • EPIC-INB-1.5-C: RBAC & Auth Layer — role enforcement, permission checks, routing middleware (REQ-001 AC-3). Target: v1.5.
  • EPIC-INB-1.5-D: Design System Compliance — responsive layouts, navigation, visual feedback (REQ-001 AC-4). Target: v1.5.

Success criteria (MAJOR v1)

• Every Gitea Issue in v1.x scope traces to a stated Goal above.
• Every Initiative is a sub-issue of the MAJOR v1 umbrella Issue.
• Every Epic is a sub-issue of its parent Initiative and lives in a Gitea Milestone from the ## MINOR release list.
• A Pillar I Gate PR for this Roadmap is merged by the CPO (or by the CEO on the CPO's behalf, per INB-123) before the SAA creates the umbrella, label, Milestones, branch, or Issue tree.
• Post-gate, the umbrella Issue carries every Initiative as a sub-issue and is blockedBy the gate PR.

Out of scope (MAJOR v1)

• v2.x scope. A new MAJOR requires its own Roadmap + Gate.
• The 5 DEF-V1.4-1..DEF-V1.4-5 items (container hardening expansion, encryption-at-rest, data-retention purge, NocoDB audit log schema, encrypted offsite backup) — deferred to v1.5+ per inboxos#18.
• Any work that bypasses dual-approval governance on main (per INB-328).

Sequencing principles

1. Ship the smallest user-visible outcome first. A live pipeline beats a perfect pipeline.
2. Validate before scaling. Land capability on a 100MB slice before committing to the full archive.
3. Idempotency before throughput. UPSERT and natural-key discipline land before bulk processing.
4. Observability before features. Logs and metrics for what is already live before the next feature.
5. Reversible over clever. Every milestone has a rollback path the CTO can name.
6. Governance before speed. Dual-approval + audit-trail enforcement is not optional. (Added 2026-06-09 by SAA in response to INB-328.)

Change log

Date	Author	Change
2026-06-08	CEO	Initialized document per Board mandate INB-123. CPO owns from this point forward.
2026-06-09	SAA	Added ## MAJOR scope, ## MAJOR Umbrella, ## MINOR release list, ## Goals (verbatim), ## Initiatives, and ## Success criteria / ## Out of scope headings per the SAA's Pillar I governance model. Retained the CPO-owned ## Milestones body, the ## Sequencing principles, and the ## Change log block unchanged. Bound to the MAJOR v1 umbrella Issue (populated on gate passage). Pending Pillar I Gate PR.
2026-06-10	SAA	Added Goal 5 (REQ-001 — Mailbox & Administrative Management Interface), Initiative INTV-5 with four Epics (EPIC-INB-1.5-A..D), and MINOR v1.5 to the release list. Open questions resolved on Gitea issue #107. Roadmap revision pending Pillar I Gate PR.