Summary
aidlc-worktree.ts (the Construction-phase primitive that all Bolt/Unit worktrees flow through) hard-refuses to run when invoked from inside any linked git worktree. Developers whose normal workflow is one-worktree-per-branch — a common setup — are locked out of Construction with no supported path forward.
What's there today
assertNotSiblingWorktree (core/tools/aidlc-worktree.ts:99-132) resolves git rev-parse --show-toplevel and compares it to the parent of --git-common-dir. If they differ (i.e. cwd is inside a linked worktree), it errors before any git op:
aidlc-worktree must run from the main repo checkout, not from a sibling worktree at <path>. Bolt worktrees are siblings of the main checkout, not nested.
The guard runs on create, merge, and discard. The swarm (aidlc-swarm.ts) forks a worktree per Unit through this same primitive, so the refusal blocks autonomous Construction too.
Is the gap real?
Yes. There is no escape hatch — grepping the source turns up no AIDLC_* override and no --allow-worktree-style flag. The --repo re-anchoring handles the multi-repo case, not the multi-worktree case, so it doesn't help. The check is unconditional: a worktree-native developer simply cannot run Construction without first cd-ing to the canonical main checkout, and the error doesn't tell them where that is.
The rationale is sound (avoid the dev-worktree-vs-bolt-worktree clash), but the tool assumes the human always drives from the main checkout, which isn't a safe assumption.
Secondary: comment/placement inconsistency
The guard message says Bolt worktrees are "siblings of the main checkout, not nested," but worktreePath (core/tools/aidlc-lib.ts:1545) nests them inside the repo at <projectDir>/.aidlc/worktrees/bolt-<slug>. Worth reconciling the prose while we're here.
Proposed mitigations
Recommended: ship the actionable error now, land the auto-anchor as the real fix.
- Auto-anchor (ideal). Resolve the main checkout from
--git-common-dir and run the git ops there regardless of cwd, instead of refusing. Most robust; removes the constraint entirely.
- Opt-in override (pragmatic near-term).
AIDLC_ALLOW_WORKTREE=1 or --from-worktree so a worktree-native dev can accept the risk explicitly.
- Actionable error (minimum). Print the resolved main-checkout path in the error: "run from
<path> or set <override>."
- Document the constraint. Surface "run Construction from the main checkout" in the User Guide / troubleshooting — currently unmentioned.
Acceptance
- A developer working from a linked git worktree can run
aidlc-worktree create/merge/discard (or Construction end-to-end) without manually relocating to the main checkout, OR gets an error that names the exact directory to run from.
- The guard comment and
worktreePath placement description agree.
Files: core/tools/aidlc-worktree.ts, core/tools/aidlc-lib.ts, core/tools/aidlc-swarm.ts.
Summary
aidlc-worktree.ts(the Construction-phase primitive that all Bolt/Unit worktrees flow through) hard-refuses to run when invoked from inside any linked git worktree. Developers whose normal workflow is one-worktree-per-branch — a common setup — are locked out of Construction with no supported path forward.What's there today
assertNotSiblingWorktree(core/tools/aidlc-worktree.ts:99-132) resolvesgit rev-parse --show-topleveland compares it to the parent of--git-common-dir. If they differ (i.e. cwd is inside a linked worktree), it errors before any git op:The guard runs on
create,merge, anddiscard. The swarm (aidlc-swarm.ts) forks a worktree per Unit through this same primitive, so the refusal blocks autonomous Construction too.Is the gap real?
Yes. There is no escape hatch — grepping the source turns up no
AIDLC_*override and no--allow-worktree-style flag. The--repore-anchoring handles the multi-repo case, not the multi-worktree case, so it doesn't help. The check is unconditional: a worktree-native developer simply cannot run Construction without firstcd-ing to the canonical main checkout, and the error doesn't tell them where that is.The rationale is sound (avoid the dev-worktree-vs-bolt-worktree clash), but the tool assumes the human always drives from the main checkout, which isn't a safe assumption.
Secondary: comment/placement inconsistency
The guard message says Bolt worktrees are "siblings of the main checkout, not nested," but
worktreePath(core/tools/aidlc-lib.ts:1545) nests them inside the repo at<projectDir>/.aidlc/worktrees/bolt-<slug>. Worth reconciling the prose while we're here.Proposed mitigations
Recommended: ship the actionable error now, land the auto-anchor as the real fix.
--git-common-dirand run the git ops there regardless of cwd, instead of refusing. Most robust; removes the constraint entirely.AIDLC_ALLOW_WORKTREE=1or--from-worktreeso a worktree-native dev can accept the risk explicitly.<path>or set<override>."Acceptance
aidlc-worktree create/merge/discard(or Construction end-to-end) without manually relocating to the main checkout, OR gets an error that names the exact directory to run from.worktreePathplacement description agree.Files:
core/tools/aidlc-worktree.ts,core/tools/aidlc-lib.ts,core/tools/aidlc-swarm.ts.