Project Branching Strategy

# Static GitHub Pages App — Parallel Branching Strategy

> **Purpose:** Define a safe parallel workflow for human developers and AI coding agents building a static GitHub Pages application.
>
> **Core rule:** Every worker branch merges into one temporary integration branch. Only the validated integration branch may open a pull request into `main`.

---

## 1. Caveman Summary

```text
main is production source.

Do not work on main.

Coordinator creates:
integration-feature-name

Coordinator splits feature into small tasks.

Each agent gets one task.
Each agent gets one branch.
Each shared file gets one owner.

Agents code in parallel.
Agents test, commit, and push.
Agents open PRs into integration.

Merge passing PRs one at a time.
Run full static build after every merge.

Broken?
Stop queue.
Create repair branch.

Everything good?
Open final PR into main.

Merge main.
GitHub Actions deploys Pages.

SQLite is special.
Only one agent edits SQLite.
```

---

## 2. Deployment Model

```text
agent branches
 |
 v
integration-feature-name
 |
 v
final pull request
 |
 v
main
 |
 v
GitHub Actions build
 |
 v
GitHub Pages
```

`main` contains reviewed production source. GitHub Actions creates the static artifact. Agents never deploy worker branches or manually edit generated production files.

---

## 3. Branch Types

| Branch | Example | Purpose |
| --- | --- | --- |
| Production | `main` | Reviewed source deployed to Pages |
| Integration | `integration-nearby-map` | Temporary feature integration boundary |
| Agent | `agent/42-map-shell` | One isolated implementation task |
| Data | `data/42-oakland-locations` | Exclusive SQLite or location-data work |
| Repair | `repair/42-base-path` | One classified integration repair |
| Hotfix | `hotfix/73-pages-build` | Urgent production-source repair |

A manually maintained `gh-pages` branch is unnecessary when GitHub Actions deploys a Pages artifact.

---

## 4. Naming Rules

```text
integration-<feature-name>
agent/<issue-number>-<task-name>
data/<issue-number>-<dataset-name>
repair/<issue-number>-<failure-name>
hotfix/<issue-number>-<problem-name>
```

Examples:

```text
integration-nearby-map
agent/42-static-build
agent/42-map-shell
agent/42-accessibility
data/42-oakland-libraries
repair/42-sqlite-loader
hotfix/73-pages-base-path
```

Use lowercase names with hyphens. Name the task, not the agent provider or a meaningless session number.

---

## 5. Ten-Agent Static-App Split

The backend-oriented roles in the original workflow are replaced with work appropriate for a static Pages application.

| Agent | Example branch | Primary responsibility |
| ---: | --- | --- |
| 01 | `agent/42-static-build` | Framework configuration, base path, static output |
| 02 | `agent/42-data-reader` | Read-only SQLite/WASM adapter and location queries |
| 03 | `data/42-oakland-locations` | Schema, migrations, seed data, SQLite checkpoint |
| 04 | `agent/42-map-shell` | Map, markers, and list synchronization |
| 05 | `agent/42-filter-details` | Filters and location-detail interface |
| 06 | `agent/42-accessibility` | Keyboard, semantics, contrast, reduced motion |
| 07 | `agent/42-tests` | Unit, integration, and browser tests |
| 08 | `agent/42-privacy-security` | Privacy, CSP, dependencies, and static-site security |
| 09 | `agent/42-docs-content` | README, operating guide, and user-facing copy |
| 10 | `agent/42-pages-integration` | Pages workflow and cross-module integration |

Use fewer agents when the work cannot be divided into independent tasks. Parallelism is useful only when ownership boundaries are real.

---

## 6. Ownership Rules

Before work begins, the coordinator assigns files and directories.

```text
One task.
One owner.
One clear boundary.
```

Shared files require coordinator approval:

- `package.json`
- Dependency lockfiles
- Framework configuration
- Global styles and design tokens
- Shared TypeScript contracts
- SQLite schema and database
- GitHub Actions workflows

Two agents must not independently edit the same shared file. Sequence the tasks or assign that file to one owner.

---

## 7. Full Parallel Workflow

```mermaid
flowchart TD
 MAIN["main Production source"]
 STAGE["integration-feature-name Temporary integration"]
 COORD["Swarm coordinator"]
 PLAN["Define contracts, ownership, and tasks"]

 MAIN --> STAGE
 STAGE --> COORD
 COORD --> PLAN

 PLAN --> A1["Agent 01 Static build"]
 PLAN --> A2["Agent 02 Data reader"]
 PLAN --> A3["Agent 03 SQLite owner"]
 PLAN --> A4["Agent 04 Map UI"]
 PLAN --> A5["Agent 05 Filters"]
 PLAN --> A6["Agent 06 Accessibility"]
 PLAN --> A7["Agent 07 Tests"]
 PLAN --> A8["Agent 08 Privacy"]
 PLAN --> A9["Agent 09 Docs"]
 PLAN --> A10["Agent 10 Pages integration"]

 A1 --> WORK["Commit, push, and open scoped PR"]
 A2 --> WORK
 A3 --> WORK
 A4 --> WORK
 A5 --> WORK
 A6 --> WORK
 A7 --> WORK
 A8 --> WORK
 A9 --> WORK
 A10 --> WORK

 WORK --> CI{"Branch CI passes?"}
 CI -->|No| FIX["Return to owning branch"]
 FIX --> WORK
 CI -->|Yes| QUEUE["Approved PR merge queue"]

 QUEUE --> MERGE["Merge one PR into integration"]
 MERGE --> VALIDATE["Run integrated static validation"]
 VALIDATE --> READY{"Integration healthy?"}

 READY -->|No| REPAIR["Create scoped repair branch"]
 REPAIR --> REPAIRPR["Repair PR into integration"]
 REPAIRPR --> MERGE

 READY -->|More PRs| QUEUE
 READY -->|All merged| FINAL["Final PR into main"]

 FINAL --> REVIEW["Human review and required checks"]
 REVIEW --> APPROVED{"Approved?"}
 APPROVED -->|No| REPAIR
 APPROVED -->|Yes| PROD["Merge into main"]

 PROD --> DEPLOY["Build and deploy Pages artifact"]
 DEPLOY --> VERIFY["Verify production URL"]
 VERIFY --> CLEAN["Delete temporary branches"]
```

---

## 8. Dependency-Aware Waves

Do not start all agents blindly. Release work when its contracts are ready.

### Wave 1 — Foundations

- Agent 01 defines the static build and base-path contract.
- Agent 03 defines the SQLite schema and representative seed data.
- Agent 08 drafts the privacy and static-security requirements.
- Agent 09 creates the documentation skeleton.
- Coordinator freezes shared UI and data contracts.

### Wave 2 — Implementation

- Agent 02 builds the read-only SQLite adapter.
- Agent 04 builds the map and markers.
- Agent 05 builds filters and location details.
- Agent 06 implements accessibility requirements.
- Agent 10 builds the Pages workflow.

### Wave 3 — Integration

- Agent 07 completes integrated tests.
- Agent 08 performs the final privacy and security review.
- Agent 10 validates the complete Pages artifact.

```mermaid
flowchart TD
 START["Acceptance criteria"] --> BUILD["Static build contract"]
 START --> DATA["SQLite schema"]
 START --> UX["UI contracts"]
 START --> PRIVACY["Privacy review"]

 BUILD --> READER["Read-only data adapter"]
 DATA --> READER
 READER --> MAP["Map UI"]
 READER --> FILTERS["Filters"]
 UX --> MAP
 UX --> FILTERS

 MAP --> TESTS["Integrated tests"]
 FILTERS --> TESTS
 PRIVACY --> REVIEW["Final review"]
 BUILD --> PAGES["Pages artifact"]

 TESTS --> FINAL["Integrated candidate"]
 REVIEW --> FINAL
 PAGES --> FINAL
```

---

## 9. Coordinator Setup

Create the integration branch:

```bash
git switch main
git pull --ff-only origin main
git switch -c integration-feature-name
git push -u origin integration-feature-name
```

Before worker branches are created, record:

- Feature goal and acceptance criteria
- Static output directory
- GitHub Pages base path
- Shared TypeScript contracts
- File and directory ownership
- Exclusive SQLite owner
- Dependency waves and merge order
- Required CI checks
- Production verification steps

Every worker branches from the same approved integration commit:

```bash
git switch integration-feature-name
git pull --ff-only origin integration-feature-name
git switch -c agent/42-task-name
git push -u origin agent/42-task-name
```

---

## 10. Worker Flow

```text
Read assigned issue
 |
 v
Confirm owned files
 |
 v
Implement scoped task
 |
 v
Review status and diff
 |
 v
Run required checks
 |
 v
Commit and push
 |
 v
PR into integration
```

Recommended checks:

```bash
npm run format:check
npm run lint
npm run typecheck
npm run test
npm run build
```

Commit only assigned paths:

```bash
git status
git diff --check
git diff
git add <assigned-paths>
git commit -m "feat: implement assigned static app task"
git push origin agent/42-task-name
```

Every worker PR uses:

```text
HEAD: agent/42-task-name
BASE: integration-feature-name
```

No worker targets `main` while the integration workflow is active.

---

## 11. Approved Merge Queue

Passing PRs merge serially, not simultaneously.

```text
PR approved
 |
 v
Enter merge queue
 |
 v
Update from current integration
 |
 v
Run CI again
 |
 v
Merge one PR
 |
 v
Run integrated validation
 |
 +--> pass: merge next PR
 |
 +--> fail: stop queue and repair
```

Recommended merge order:

1. Shared contracts and static-build configuration
2. SQLite schema and seed data
3. Read-only data adapter
4. Map and filter features
5. Accessibility changes
6. Tests
7. Privacy and security changes
8. Documentation
9. Pages deployment and integration changes

Follow actual dependencies rather than agent numbers.

---

## 12. SQLite Single-Writer Rule

SQLite is a binary database. Git cannot safely merge independently edited database copies.

```text
One database.
One data owner.
One active SQLite branch.
```

Allowed:

```text
integration-feature-name
 |
 v
data/42-oakland-locations
 |
 | edit records
 | checkpoint WAL
 | validate integrity
 v
PR into integration-feature-name
```

Forbidden:

```text
data/agent-a ----+
 +---> merge binary SQLite files
data/agent-b ----+
```

Before committing:

```sql
PRAGMA wal_checkpoint(TRUNCATE);
PRAGMA integrity_check;
```

The integrity result must be `ok`.

Never commit:

```gitignore
data/*.db-wal
data/*.db-shm
data/*.db-journal
data/*.db.backup
```

The data owner must attach a deterministic record summary because GitHub cannot meaningfully display a binary SQLite diff.

---

## 13. Static Pages Boundary

GitHub Pages serves static files. It does not provide a writable server filesystem or Node server.

- SQLite is packaged as a read-only site asset.
- The browser may query it through a compatible WebAssembly SQLite library.
- Database updates occur through reviewed repository branches and redeployment.
- Public visitors cannot write directly into the committed database.
- Anonymous public submissions require a separate write service or submission channel.
- Agents must not introduce authentication, server API, or runtime-database work into this static MVP.

---

## 14. Integrated Validation Gate

After each queued merge:

- [ ] Formatting passes
- [ ] Linting passes
- [ ] Type checking passes
- [ ] Unit and browser tests pass
- [ ] Static production build passes
- [ ] GitHub Pages base path works
- [ ] Internal links and assets resolve
- [ ] SQLite loads and passes integrity validation
- [ ] Map attribution is visible
- [ ] Manual search works when geolocation is denied
- [ ] Keyboard navigation works
- [ ] Mobile viewport works
- [ ] No secrets or local files enter the artifact
- [ ] Artifact size stays within budget

```mermaid
flowchart TD
 A["Merge one approved PR"] --> B["Build integrated candidate"]
 B --> C{"All checks pass?"}
 C -->|Yes| D{"More queued PRs?"}
 D -->|Yes| E["Update next PR"]
 E --> A
 D -->|No| F["Open final PR into main"]
 C -->|No| G["Stop merge queue"]
 G --> H["Create repair branch"]
 H --> I["Repair PR into integration"]
 I --> B
```

---

## 15. Repair Swarm

Do not make random direct edits on the integration branch.

```text
integration-feature-name
 |
 +--> repair/42-pages-base-path
 |
 +--> repair/42-sqlite-loader
 |
 +--> repair/42-keyboard-navigation
```

Each repair branch must:

- Own one classified failure
- Modify only affected files
- Add or update a regression test
- Pass branch CI
- Open a PR into integration
- Merge through the serial queue

If a repair changes SQLite, assign it to the current data owner or formally transfer the single-writer lock.

---

## 16. Final Pull Request

After all planned worker PRs merge and integrated validation passes:

```text
HEAD: integration-feature-name
BASE: main
```

The final PR includes:

- Feature goal and acceptance criteria
- Merged worker PR list
- Integrated test results
- Static build artifact or screenshots
- SQLite summary when applicable
- Accessibility results
- Privacy and security review
- Deployment impact
- Rollback instructions
- Known limitations

Only a reviewed merge into `main` may trigger the production Pages deployment.

---

## 17. Branch Protection

Protect `main` with:

- Pull request required
- Required CI checks
- Required conversation resolution
- Stale approval dismissal
- No direct pushes
- No force pushes
- Deployment restricted to the approved Pages workflow

Recommended checks:

```text
format
lint
typecheck
test
build
pages-path-check
accessibility
database-integrity
```

Require only checks implemented by the repository.

---

## 18. Merge Strategy

Use squash merge for worker PRs:

```text
feat: add map shell (#42)
feat: add read-only SQLite loader (#43)
data: add Oakland pilot locations (#44)
test: cover static location filtering (#45)
```

Use a merge commit for the final integration PR when preserving the complete integration boundary helps auditing and rollback:

```text
release: add nearby charging map MVP
```

The repository may squash the final PR if a linear history is preferred. Choose one convention and document it.

---

## 19. Forbidden Flows

```text
agent/01 ---+
agent/02 ---+---> main
agent/03 ---+
```

```text
data/agent-a ---+
 +---> charging-map.db
data/agent-b ---+
```

```text
agent/task ---> GitHub Pages production
```

```text
browser form ---> static SQLite file
```

Also forbidden:

- Parallel edits to the same dependency lockfile
- Direct unreviewed fixes on the integration branch
- Failed-CI branches entering the merge queue
- Mixing unrelated features in one worker branch
- Committing SQLite temporary files or secrets

---

## 20. Pull Request Matrix

| Source | Target | Allowed? |
| --- | --- | ---: |
| `agent/*` | `integration-feature-name` | Yes |
| `data/*` | `integration-feature-name` | Yes, one SQLite writer |
| `repair/*` | `integration-feature-name` | Yes |
| `integration-feature-name` | `main` | Yes, after full validation |
| `hotfix/*` | `main` | Yes, with review and CI |
| `agent/*` | `main` | No during integration |
| `data/*` | `main` | No during integration |
| Any worker | Pages production | No |
| Failed CI branch | Integration | No |

---

## 21. Coordinator Checklist

- [ ] Pull latest `main`
- [ ] Define acceptance criteria
- [ ] Create integration branch
- [ ] Define shared contracts
- [ ] Assign file ownership
- [ ] Assign one SQLite owner
- [ ] Identify dependency waves
- [ ] Define merge order
- [ ] Confirm Pages base path
- [ ] Track worker branches and PRs
- [ ] Prevent shared-file collisions
- [ ] Maintain serial merge queue
- [ ] Stop queue on failure
- [ ] Run validation after every merge
- [ ] Open final PR into `main`
- [ ] Verify production deployment
- [ ] Delete temporary branches

---

## 22. Every Agent Checklist

- [ ] Read assigned task and acceptance criteria
- [ ] Confirm owned and prohibited files
- [ ] Branch from the specified integration commit
- [ ] Implement only assigned scope
- [ ] Review `git status` and `git diff`
- [ ] Run relevant tests and static build
- [ ] Commit intentionally
- [ ] Push worker branch
- [ ] Open PR into integration
- [ ] Respond to CI and review feedback
- [ ] Do not merge unless authorized
- [ ] Report blockers and dependencies clearly

---

## 23. Final Rule

```text
One feature.
One temporary integration branch.

Many scoped workers.
One branch per worker.
One owner per shared file.

One SQLite owner.
No binary database merging.

Every worker PR targets integration.
Passing PRs enter a serial merge queue.

Integration validates after every merge.
Failures create repair branches.

Only integration opens PR into main.
Only main deploys GitHub Pages.

main stays stable.
Pages stays reproducible.
Parallel work stays reviewable.
```

Navigation Menu

Uh oh!

Project Branching Strategy #3

Static GitHub Pages App — Parallel Branching Strategy

1. Caveman Summary

2. Deployment Model

3. Branch Types

4. Naming Rules

5. Ten-Agent Static-App Split

6. Ownership Rules

7. Full Parallel Workflow

8. Dependency-Aware Waves

Wave 1 — Foundations

Wave 2 — Implementation

Wave 3 — Integration

9. Coordinator Setup

10. Worker Flow

11. Approved Merge Queue

12. SQLite Single-Writer Rule

13. Static Pages Boundary

14. Integrated Validation Gate

15. Repair Swarm

16. Final Pull Request

17. Branch Protection

18. Merge Strategy

19. Forbidden Flows

20. Pull Request Matrix

21. Coordinator Checklist

22. Every Agent Checklist

23. Final Rule

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Branch	Example	Purpose
Production	`main`	Reviewed source deployed to Pages
Integration	`integration-nearby-map`	Temporary feature integration boundary
Agent	`agent/42-map-shell`	One isolated implementation task
Data	`data/42-oakland-locations`	Exclusive SQLite or location-data work
Repair	`repair/42-base-path`	One classified integration repair
Hotfix	`hotfix/73-pages-build`	Urgent production-source repair

Agent	Example branch	Primary responsibility
01	`agent/42-static-build`	Framework configuration, base path, static output
02	`agent/42-data-reader`	Read-only SQLite/WASM adapter and location queries
03	`data/42-oakland-locations`	Schema, migrations, seed data, SQLite checkpoint
04	`agent/42-map-shell`	Map, markers, and list synchronization
05	`agent/42-filter-details`	Filters and location-detail interface
06	`agent/42-accessibility`	Keyboard, semantics, contrast, reduced motion
07	`agent/42-tests`	Unit, integration, and browser tests
08	`agent/42-privacy-security`	Privacy, CSP, dependencies, and static-site security
09	`agent/42-docs-content`	README, operating guide, and user-facing copy
10	`agent/42-pages-integration`	Pages workflow and cross-module integration

Source	Target	Allowed?
`agent/*`	`integration-feature-name`	Yes
`data/*`	`integration-feature-name`	Yes, one SQLite writer
`repair/*`	`integration-feature-name`	Yes
`integration-feature-name`	`main`	Yes, after full validation
`hotfix/*`	`main`	Yes, with review and CI
`agent/*`	`main`	No during integration
`data/*`	`main`	No during integration
Any worker	Pages production	No
Failed CI branch	Integration	No

Uh oh!

Project Branching Strategy #3

Description

Static GitHub Pages App — Parallel Branching Strategy

1. Caveman Summary

2. Deployment Model

3. Branch Types

4. Naming Rules

5. Ten-Agent Static-App Split

6. Ownership Rules

7. Full Parallel Workflow

8. Dependency-Aware Waves

Wave 1 — Foundations

Wave 2 — Implementation

Wave 3 — Integration

9. Coordinator Setup

10. Worker Flow

11. Approved Merge Queue

12. SQLite Single-Writer Rule

13. Static Pages Boundary

14. Integrated Validation Gate

15. Repair Swarm

16. Final Pull Request

17. Branch Protection

18. Merge Strategy

19. Forbidden Flows

20. Pull Request Matrix

21. Coordinator Checklist

22. Every Agent Checklist

23. Final Rule

Activity

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions