seams: the parallel-execute worktree fork point IS caller-selectable via worktree.baseRef #68

New issue

Closed

opened 2026-07-28 17:41:29 +00:00 by crenshawdev · 0 comments

crenshawdev commented

2026-07-28 17:41:29 +00:00

(Migrated from github.com)

What happened

cadence-core/references/seams.md states that the parallel-execute worktree's fork point cannot be controlled:

# cadence-core/references/seams.md:54-60
**Worktree isolation.** The host provides the worktree for the parallel
`/cad-execute` path (`workflows/execute.md`'s `execute_parallel` step); its
fork point is host-owned and NOT caller-controllable. Cadence issues no
`git worktree add` anywhere in `cadence-core/bin`, `agents/`, `skills/` or
`cadence-core/workflows/`, so it cannot pin the base commit a worktree
branches from. A worktree has been observed 31 commits behind, missing both
the phase CONTEXT and its own `PLAN-2.md` (`.planning/CAPTURE.md:5`).

The second sentence is false. The fork point is controllable, and the setting that controls it describes Cadence's exact use case.

Per the worktrees documentation, worktree.baseRef takes two values:

"fresh" (default): branch from the repository's default branch on the remote, usually main.
"head": branch from the current local HEAD, carrying unpushed commits and feature-branch state. The doc's stated use case is verbatim "Use this when isolating subagents that need to operate on in-progress work."

And on subagents specifically: "Subagent worktrees use the same base branch as --worktree, so they branch from your repository's default branch unless worktree.baseRef is set to head."

The default is "fresh". That is the root cause of the observed failure. A phase's CONTEXT and its PLAN-2.md live in unpushed commits on the integration branch, a "fresh" worktree forks from origin/main and does not have them, and the executor lands 31 commits behind holding none of its own inputs.

What you expected

seams.md to state the constraint that actually holds, and the parallel path to run against a base that contains its own plan files.

Reproduction

Read cadence-core/references/seams.md:54-60 for the claim, then the "Choose the base branch" section of https://code.claude.com/docs/en/worktrees for the setting that contradicts it.

Observed failure already recorded at .planning/CAPTURE.md:5.

Environment

Claude Code version: 2.1.220
node --version: v26.4.0
OS: Linux (CachyOS, 7.1.5-1-cachyos)
Cadence: v1.4.0 at fba5879
Relevant config: parallelization.enabled, parallelization.use_worktrees (the parallel arm is opt-in and off by default)

Notes, and two honest qualifications

It is a setting, not a per-dispatch parameter. worktree.baseRef lives in the Claude Code settings cascade. A plugin cannot set it unilaterally, and Cadence should not silently write a user's settings. So the fix is not a change at the dispatch site. The realistic shape is a preflight in execute.md's execute_parallel gate that reads the effective value and refuses to parallelize under "fresh", plus a /cad-config step that offers to write "head", plus the corrected prose in seams.md.

It wants a minimum Claude Code version. Worktree base-branch behavior changed at 2.1.208 (before that, a fresh worktree used whatever origin/HEAD happened to be cached locally). Whatever Cadence claims about fork points should name the version the claim holds for.

One nuance to carry into the fix: inside a worktree, "head" resolves to that worktree's HEAD, not the main checkout's.

Do not remove the executor's assertion. agents/cad-executor.md's <worktree_mode> check, which asserts its own PLAN-<k>.md exists before task 1 and halts blocked naming the missing path, stays regardless. It is cheap, it caught this failure, and a setting the user can change back is not a guarantee. What changes is that the halt stops being the only answer Cadence has.

This finding predates the v1.4.0 close, which restated the worktree binding across six surfaces on the strength of the claim above. Every one of those surfaces needs the corrected version.

## What happened `cadence-core/references/seams.md` states that the parallel-execute worktree's fork point cannot be controlled: ``` # cadence-core/references/seams.md:54-60 **Worktree isolation.** The host provides the worktree for the parallel `/cad-execute` path (`workflows/execute.md`'s `execute_parallel` step); its fork point is host-owned and NOT caller-controllable. Cadence issues no `git worktree add` anywhere in `cadence-core/bin`, `agents/`, `skills/` or `cadence-core/workflows/`, so it cannot pin the base commit a worktree branches from. A worktree has been observed 31 commits behind, missing both the phase CONTEXT and its own `PLAN-2.md` (`.planning/CAPTURE.md:5`). ``` The second sentence is false. The fork point is controllable, and the setting that controls it describes Cadence's exact use case. Per [the worktrees documentation](https://code.claude.com/docs/en/worktrees#choose-the-base-branch), `worktree.baseRef` takes two values: - `"fresh"` (default): branch from the repository's default branch on the remote, usually `main`. - `"head"`: branch from the current local `HEAD`, carrying unpushed commits and feature-branch state. The doc's stated use case is verbatim *"Use this when isolating subagents that need to operate on in-progress work."* And on subagents specifically: *"Subagent worktrees use the same base branch as `--worktree`, so they branch from your repository's default branch unless `worktree.baseRef` is set to `head`."* The default is `"fresh"`. That is the root cause of the observed failure. A phase's CONTEXT and its `PLAN-2.md` live in unpushed commits on the integration branch, a `"fresh"` worktree forks from `origin/main` and does not have them, and the executor lands 31 commits behind holding none of its own inputs. ## What you expected `seams.md` to state the constraint that actually holds, and the parallel path to run against a base that contains its own plan files. ## Reproduction Read `cadence-core/references/seams.md:54-60` for the claim, then the "Choose the base branch" section of `https://code.claude.com/docs/en/worktrees` for the setting that contradicts it. Observed failure already recorded at `.planning/CAPTURE.md:5`. ## Environment - Claude Code version: 2.1.220 - `node --version`: v26.4.0 - OS: Linux (CachyOS, 7.1.5-1-cachyos) - Cadence: v1.4.0 at `fba5879` - Relevant config: `parallelization.enabled`, `parallelization.use_worktrees` (the parallel arm is opt-in and off by default) ## Notes, and two honest qualifications **It is a setting, not a per-dispatch parameter.** `worktree.baseRef` lives in the Claude Code settings cascade. A plugin cannot set it unilaterally, and Cadence should not silently write a user's settings. So the fix is not a change at the dispatch site. The realistic shape is a preflight in `execute.md`'s `execute_parallel` gate that reads the effective value and refuses to parallelize under `"fresh"`, plus a `/cad-config` step that offers to write `"head"`, plus the corrected prose in `seams.md`. **It wants a minimum Claude Code version.** Worktree base-branch behavior changed at 2.1.208 (before that, a fresh worktree used whatever `origin/HEAD` happened to be cached locally). Whatever Cadence claims about fork points should name the version the claim holds for. One nuance to carry into the fix: inside a worktree, `"head"` resolves to that worktree's `HEAD`, not the main checkout's. **Do not remove the executor's assertion.** `agents/cad-executor.md`'s `<worktree_mode>` check, which asserts its own `PLAN-<k>.md` exists before task 1 and halts `blocked` naming the missing path, stays regardless. It is cheap, it caught this failure, and a setting the user can change back is not a guarantee. What changes is that the halt stops being the only answer Cadence has. This finding predates the v1.4.0 close, which restated the worktree binding across six surfaces on the strength of the claim above. Every one of those surfaces needs the corrected version.