50 lines
2.7 KiB
Markdown
50 lines
2.7 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.
|
|
|
|
## 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.
|
|
- 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.
|
|
|
|
## 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)
|