Inboxintel/docs/discovery/10-git-plan.md

10 — Git Implementation Plan (Phase 10)

Turns the roadmap into executable Git work, on the workflow already in place (../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 §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.