BFDev Monolithic Git v2 Stories¶

Context Summary¶

Product area: BFDev repository topology, contributor workflow, and downstream sync.
Primary entrypoint: bf-dev clone, branch/worktree workflow, and merge-request flow.
Repo scope: bf-dev root docs, repository structure, and sync workflow for imported bf-* directories.
Scope basis: spec and the April 28, 2026 monolithic Git planning brief.
Story focus: one canonical contributor outcome where bf-dev becomes the authoritative authoring surface and downstream per-service repositories become an implementation detail for day-to-day work.
Scope guardrail: downstream repositories remain in place for current delivery in this phase, but they should be abstracted away from normal contributor authoring flow.
Linear mirror rule: this story should anchor the matching Linear project description and any mirrored story issue.

Author product-oriented vertical slices from one repository¶

User Story¶

As a full-stack contributor, I want to work from one authoritative bf-dev repository that abstracts away downstream per-service repositories while still keeping them synchronized during the transition so that I can develop, review, and deliver product-oriented vertical slices with one branch, one worktree, and one merge request.

Acceptance Criteria¶

A contributor can clone bf-dev once and access the in-scope BetterFleet project code needed for cross-service work without separately cloning each downstream service repository.
A contributor can create one branch and one worktree in bf-dev that spans changes across multiple imported bf-* directories.
A product-oriented change that touches multiple imported directories can be authored and reviewed as one coherent bf-dev merge request rather than being split into separate contributor-facing repository workflows.
Day-to-day contributor workflow does not require manual per-service branching, committing, pushing, or merge-request creation against the downstream repositories.
The transition workflow still synchronizes owned directory changes back to the current downstream repositories so existing pipelines, deployments, and infrastructure ownership continue to work.
The contributor-facing workflow remains stable even if the organization later decides to retire or absorb the downstream per-service repositories into bf-dev.

Dependencies¶

Aligns with ADR 0006 - Trunk-Based Development, especially the bias toward small trunk-friendly vertical slices instead of horizontally fragmented multi-repo batches.
Aligns with ADR 0007 - Generalised principle for automation, especially the requirement that downstream synchronization stays explicit, safe, and auditable.
Aligns with ADR 0008 - Naming Repositories, Services, and URLs, especially the continued use of canonical bf-* project naming inside the unified repository.
Aligns with ADR 0014 - Service Granularity, especially the requirement that repository-topology consolidation remains distinct from runtime or service consolidation.

Split Signals¶

If branch/worktree ergonomics and downstream synchronization need to be delivered separately, split the contributor authoring surface from the sync-back continuity story.
If reviewer needs diverge materially from contributor authoring needs, split unified authoring from unified review into separate stories.
If long-term retirement of the downstream repositories becomes an active delivery goal rather than a guardrail, shape that as a separate follow-up story instead of widening this one.