# worktree parallelism

_Status: direction — as of 2026-07-16_
_Connects to: [pipeline-stages](pipeline-stages.md), [spec-and-ticket-layer](spec-and-ticket-layer.md), [horizon](horizon.md), [overview](../OVERVIEW.md)_

## Purpose

Defines how os-sdlc scopes concurrency: worktree-per-spec, sequential tickets within a spec,
parallelism across specs. Load this when designing worktree lifecycle automation or any
multi-ticket/multi-spec orchestration for os-sdlc.

## Design

- **Worktree-per-spec.** Tickets belonging to one spec run sequentially inside a single
  worktree — this avoids intra-spec merge conflicts entirely, since only one pipeline run is
  ever touching that worktree's files at a time.
- **Parallelism happens across specs**, not within one. Multiple specs, each with its own
  worktree and its own sequential ticket queue, can run concurrently to keep overall progress
  rolling without any single spec's pipeline blocking another's.
- **Merge is a human gate in v1** — consistent with [pipeline-stages](pipeline-stages.md)'s
  final stage. No automated merge choreography yet.
- **Tiered isolation ladder** (from the vault taxonomy note): no isolation → single worktree →
  N parallel worktrees → full sandbox. os-sdlc v1 sits at "single worktree" per spec; a router
  agent that picks the isolation tier per task is explicitly deferred until a concrete case
  proves it's needed — not built ahead of that need.
- **Known bug — cc-os Forgejo issue #73:** `.cc-os/config` is untracked, so worktrees don't
  inherit the tracker key, and `os-backlog` issue-create fails inside them. This blocks
  ticket-intake (stage 1 of [pipeline-stages](pipeline-stages.md)) from working inside a
  worktree today. The factory needs a native fix — either walking up to the owning repo root
  to find the config, or provisioning `.cc-os/config` at worktree-creation time. Per
  [pipeline-stages](pipeline-stages.md)'s build sequencing: the once-only tracer walk
  hand-patches around this bug by manually copying `.cc-os/config` into the walk's worktree;
  the native fix (chosen from what the walk shows) is a hard dependency of the wiring step
  that follows the walk, so it must land before wiring starts.

## Open questions

- Whether Pocock's `wayfinder:map` tags should drive merge choreography — check the vault
  note `matt-pocock-skills-v1-1-changes.md` when designing this; not yet evaluated against
  os-sdlc's spec/ticket model. Related, sharper version of the same question: whether each
  spec should get an orchestration/"map" ticket that tracks its constituent tickets and their
  pipeline state, owned by the orchestrator, and used to drive merge choreography across a
  spec's worktree.
- Worktree lifecycle automation: who creates a worktree for a new spec, who cleans it up after
  merge, and what triggers each.
- Branch naming convention for spec-level and (if they ever become worth it) per-ticket
  branches under a spec branch.
- **PR-machinery plan.** [pipeline-stages](pipeline-stages.md) stage 8 is a human merge gate
  in v1. Before that gate can automate, a plan is needed for what replaces it: PR creation,
  review attachment, and merge policy. Not scoped yet — flagged here so automation of the
  merge gate doesn't get built without one.

## Sources

- SecondBrain vault: `agentic-sdlc-ai-developer-workflow-taxonomy.md` (tiered isolation
  ladder), `matt-pocock-skills-v1-1-changes.md` (wayfinder:map)
- cc-os Forgejo issue #73 (`.cc-os/config` untracked, worktree tracker-key inheritance bug)
- ADR-0042 (2026-07-16, Planka retirement / git-issues-only os-backlog)
- `plugins/os-sdlc/OVERVIEW.md`
- 2026-07-16 design session (this doc's origin)
