Session Git — Concurrent Lanes

1. Purpose

Align written process, tooling, and day-to-day practice. SAGP v1.2 still reads as one session → one branch (session-{N}). In production, teams routinely run 2–4 concurrent sessions on the same branch (often a range name such as session-264-269_new). That is valid; the doc and some checks were wrong, not the workflow.

This document is the authoritative spec for branch/session semantics. SAGP v1.3 (sessions-git-protocol.mdc) incorporates these rules by reference.

2. Problem statement

What was always correct: [S{N}.{sub}] commit tags, explicit git add <files>, stash naming, and not working directly on main.

3. Target model (normative)

3.1 Definitions

• Session — A numbered unit of work (manifest S{N}.json, MCP sessionNumber, history entries).
• Branch lane — A Git branch used as a shared integration line for one or more sessions over time.
• Range branch — A lane whose name encodes a span (e.g. session-264-269, session-264-269_new). It may intentionally correspond to multiple session IDs in that range.
• Attribution — Per commit, via [S{N}.{sub}]. The branch name does not uniquely identify a single session when multiple sessions share the lane.

3.2 Rules (replace rigid §2 branch rules)

1. Many sessions MAY share one branch. Prefer one stable lane over spawning redundant session-{N} branches when work is tightly coupled or concurrent.
2. Branch name = coarse scope, not ownership. It answers: “Which line of history / integration bucket?” not “who owns every commit.”
3. Commit message = fine-grained ownership. Every commit MUST remain tagged with [S{N}.{sub}] for the session that owns that change.
4. Preflight / MCP “synced” means: current branch plausibly relates to the enforced session (e.g. range token includes N; optional cross-check against that session’s manifest gitBranch if present). It does not mean HEAD must equal only session-{N}.
5. Do not mix unrelated work without tagging. If you touch files for session B while on a lane also used for session A, split commits or clear [S{B}.{sub}] on those commits — same as today; the rule is attribution, not branch exclusivity.
6. main — unchanged: no direct commits; merge via PR or controlled merge policy.

3.2a Boundary: what changes vs what does not

No new manifest fields are required for concurrent lanes. No aggregating multiple sessions into one manifest.

3.3 Naming conventions (flexible, not exhaustive)

Dropped from this spec: integrate/{N}-{M} disposable branches. Range lanes already act as the integration line for concurrent work; merging to main is the remaining integration step (PR / policy). If someone ever needs a throwaway pre-main combine, they can use any local branch name—no separate convention required.

Non-goals: Mandating a single global pattern for all repos; teams may keep local variants if attribution rules hold.

3.4 Manifests (sessions/manifests/S{N}.json)

• Unchanged: Each manifest remains only data for session N (per existing schema and team conventions).
• gitBranch on sub-sessions (as today) — Optional audit of which lane that sub-session used; tooling may read it for hints, but Git flexibility does not depend on new manifest fields.

3.5 PRs and merges to main (resolved)

Decision: Yes — merge-related metadata must preserve session traceability.

1. PR title — Include at least one [S{N}.{sub}] tag (typically the primary session driving the PR). If several sessions share the lane with similar weight, use one tag in the title and list the rest in the description (e.g. “Also: [S268.2][S267.1]”).
2. Merge commit message (merge commits, or squash subject/body) — Include [S{N}.{sub}] for every session that contributed material commits in that PR, or a single line such as Sessions: S269.3, S268.2, S267.1 so git log remains grep-friendly.
3. Squash-merge — Default squash subject should carry the lead session tag; squash body should list other [S*] tags copied from commits if multiple sessions are in the branch.

This keeps main history searchable by session tag without changing manifest layout.

3.6 Release notes / changelog (resolved)

Approach: Prefer automation from Git, not new manifest fields.

1. Technical “what merged” — git log on main with session tags ([S\d+(?:\.\d+)?\]) is the canonical list; scripts can group by session number.
2. User-facing changelog — Generate draft bullets from tagged merge/PR lines, then edit for readability; optional deep links to docs/english/sessions/... or manifest titles read as reference (manifests stay per-session; they are not merged into a mega-file).
3. No requirement to mirror every commit in manifests; manifests remain session journals, not release registers.

4. Tooling expectations

5. Non-goals

• Replacing Git or commit tags with branch-only identity.
• Automatic inference of “which session” from branch name alone on shared lanes.
• Forcing one branch per developer or one branch per machine.
• Changing sessions/manifests/S{N}.json schema or collapsing multiple sessions into one manifest — Git/process only.

6. Rollout plan

Phase 0 — Decisions (owner: you / tech lead)

• Accept concurrent-lanes as official; SAGP v1.3 + this spec published.
• Default MCP policy: multi-session (implemented in MCP); strict is opt-in via MCP_GIT_BRANCH_POLICY.
• Manifests: keep per-session only; no schema change for concurrent lanes (see §3.2a).

Phase 1 — Documentation (high priority)

• Update sessions-git-protocol.mdc: v1.3 — INIT, §2, §5, §8–§10, §13 flow, §14 replaces integrate/*.
• AGENTS.md / CLAUDE.md — concurrent lanes + link to this spec.
• This file status: active.

Phase 2 — Tooling polish (optional)

• Optional: yarn session:check soft-warning if current git branch does not reference enforced session (same heuristic as MCP multi-session policy), without requiring manifest schema changes.
• Optional: script to draft release notes from git log main --grep='\\[S' (or equivalent) grouped by session tag.

Phase 3 — Agent / human training

• Short internal note for agents: “Wrong branch” = attribution risk, not “branch string ≠ session-{N}.”
• Code review checklist: shared lane ⇒ verify commit tag matches owning session.

Phase 4 — Cleanup

• Archive or redirect any old diagrams/docs that show only session-{N}.
• Prune stale local branches (operational, not spec).

7. Success criteria

• Agents stop receiving false “branch mismatch” when on a valid range / shared lane.
• Written protocol matches how 2–4 concurrent sessions actually work.
• Attribution remains traceable via [S{N}.{sub}] on every meaningful commit.

8. Resolved decisions (formerly open questions)

9. Revision history