61 lines
3.6 KiB
Markdown
61 lines
3.6 KiB
Markdown
# 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)
|