docs: discovery blueprint + multi-provider design (#8)

2026-07-01 19:59:53 +02:00
parent 9ee5d757f5
commit 4ce2df0a2b
27 changed files with 2032 additions and 0 deletions
@@ -0,0 +1,60 @@
+# 10 — Git Implementation Plan (Phase 10)
+
+Turns the [roadmap](09-roadmap.md) into executable Git work, on the workflow already in
+place ([../WORKFLOW.md](../WORKFLOW.md)): trunked `develop`/`main`, Conventional Commits,
+PR-gated CI/Security, auto-deploy to staging, tag-gated production.
+
+## Structure: Epics → Features → Tasks
+- **Epic** = a roadmap theme → a milestone + a long-lived integration effort.
+- **Feature** = one shippable slice → one `feature/*` branch → one PR into `develop`.
+- **Task** = one atomic commit (conventional) within a feature branch.
+
+## Epics (mapped to releases)
+| Milestone | Epic | Example feature branches |
+|-----------|------|--------------------------|
+| **v1.0.0** | `epic/design-system` | `feature/design-tokens` · `feature/app-shell` · `feature/themes-dark-light` |
+| **v1.0.0** | `epic/search-core` | `feature/search-ranking` · `feature/fts-multifield` · `feature/search-fuzzy-trgm` · `feature/search-chips` · `feature/saved-recent-searches` · `feature/search-why-matched` · `feature/keyset-pagination` |
+| **v1.0.0** | `epic/perf-and-debt` | `feature/trgm-indexes` · `feature/virtualised-list` · `feature/code-splitting` · `fix/ef-queryfilter-warning` · `feature/language-aware-fts` |
+| **v1.0.0** | `epic/ai-foundation` | `feature/ai-abstraction` · `feature/embedding-provider` · `feature/ai-vram-guard` · `feature/ai-thread-summary` · `feature/ai-followup-detect` · `feature/ai-reply-suggest` |
+| **v1.1.0** | `epic/assisted-search` | `feature/nl-search-parse` · `feature/people-search` · `feature/attachment-filename-search` · `feature/search-bulk-actions` |
+| **v1.1.0** | `epic/ai-productivity` | `feature/inbox-brief` · `feature/task-calendar-extract` · `feature/categorise-tail` · `feature/priority-v1` |
+| **v1.2.0** | `epic/semantic` | `feature/pgvector-schema` · `feature/embedding-backfill` · `feature/semantic-search` · `feature/find-similar` · `feature/near-dup` · `feature/thread-insights` |
+| **v2.0.0** | `epic/ambitious-ai` | `feature/ask-your-inbox-rag` · `feature/entity-facets` · `feature/attachment-ocr` · `feature/phishing-reasoning` · `feature/knowledge-graph` |
+| **v3.0.0** | `epic/platform` | `feature/rules-engine` · `feature/collaboration` · `feature/multi-account` · `feature/plugin-api` · `feature/mobile` |
+
+## Branch naming
+- `feature/<kebab-scope>` · `fix/<kebab>` · `hotfix/<kebab>` (off `main`) · optional
+  `release/x.y.0` for stabilisation. Epics tracked via milestone/label, not a long branch
+  (avoid merge hell); features integrate continuously into `develop`.
+
+## Commit strategy
+- **Conventional Commits** (already used): `type(scope): summary`. Types drive SemVer:
+  `feat`→minor, `fix`→patch, `feat!`/`BREAKING CHANGE`→major.
+- One logical change per commit; **docs updated in the same commit/PR** as the behaviour
+  they describe (enforced by review checklist — see below).
+
+## PR strategy
+- `feature/* → develop`, **squash-merge**; `develop → main`, **merge commit** (release boundary).
+- **Required checks** (already enforced): `CI/backend`, `CI/frontend`, `Security/secrets`,
+  `Security/dependencies`. Merge to `develop` auto-deploys **staging**.
+- **PR checklist:** tests added (unit + integration for API changes) · docs updated ·
+  AI features have a **Null/AI-off path** · no secret committed · perf-sensitive paths have
+  an index/plan note.
+
+## Release milestones (tags on `main`)
+| Tag | Contents | Gate |
+|-----|----------|------|
+| `v1.0.0` | Redesign + deterministic search + AI foundation & first wins | Redesign parity + search benchmarks green |
+| `v1.1.0` | Assisted search + AI productivity | NL parse accuracy + extraction quality bar |
+| `v1.2.0` | Semantic tier | Backfill complete + hybrid-rank quality bar |
+| `v2.0.0` | Ambitious AI (RAG, vision, graph) | RAG citation accuracy + VRAM stability |
+| `v3.0.0` | Platform (collab, rules, plugins, mobile) | — |
+- Cutting a tag = the production-promotion action (see [../WORKFLOW.md](../WORKFLOW.md) §5–6);
+  `deploy-prod.yml` fires on `v*` once the Linux server + its runner exist.
+- Interim work ships as `0.x`/pre-release increments on `develop`; `v1.0.0` is the first
+  "world-class" cut.
+
+## Docs-alongside-code (hard rule)
+Every feature PR updates the relevant doc: `docs/discovery/*` decisions graduate into
+`docs/` living docs (architecture, search, AI, API reference) as they're implemented, and
+`CHANGELOG.md` gains an entry. Discovery docs are the *source*; implementation keeps them true.