fix(seams): the worktree fork point is selectable via worktree.baseRef #79

Merged

crenshawdev merged 6 commits from cadence/68-worktree-baseref into main

2026-07-28 19:26:37 +00:00

crenshawdev commented

2026-07-28 19:25:47 +00:00

(Migrated from github.com)

seams.md claimed the parallel-execute worktree's fork point is host-owned and not caller-controllable. It is controllable, via the host's worktree.baseRef, and the default (fresh, which forks from the remote default branch) is the direct cause of the recorded failure where an executor landed 31 commits behind holding neither the phase CONTEXT nor its own PLAN-2.md.

v1.4.0 restated that claim across several surfaces on the strength of it, so the correction is not confined to one file.

What changed

The claim, corrected in 8 places. seams.md (the source), agents/cad-executor.md (the <worktree_mode> Reason line only), cadence-core/references/git.md, config.schema.json, workflows/config.md, METHOD.md, branch-decision.mjs's runtime reason string, and .planning/REQUIREMENTS.md GIT-01. Mentions that make no fork-point or controllability claim were deliberately left alone.

A preflight. New read-only seam cadence-core/bin/worktree-base.mjs resolves the effective worktree.baseRef through the real settings cascade, rooted at the main checkout via git rev-parse --git-common-dir so it works from inside a worktree. It emits {ok, baseRef, source, parallelSafe, reason}, skips a malformed layer rather than dying on it, refuses on an unrecognized value, and never writes. execute.md's choose_path gate now requires it and falls back to sequential when the value is fresh.

A /cad-config offer. Shows the file first, merges the single key preserving everything else, never touches managed policy, and does nothing if declined. Offered only when parallelization.enabled and use_worktrees are both on.

Constraints honoured

The plugin never silently writes a user's settings. It offers.
cad-executor.md's <worktree_mode> assertion is untouched and stays. A setting the user can change back is not a guarantee.
Claims are scoped to Claude Code >= 2.1.208, where the behaviour holds.
Inside a worktree, head resolves to that worktree's HEAD, and the prose says so.

Judgment call

The issue asked for the preflight in execute_parallel. The gate that actually decides parallel-vs-sequential is choose_path, so it lives there with a pointer from execute_parallel.

Verification

node --test cadence-core/bin/*.test.mjs → 737 pass, 0 fail (10 new in worktree-base.test.mjs)
npx tsc -p tsconfig.ci.json → exit 0
node cadence-core/bin/self-verify.mjs → {"ok":true,...,"problems":[]}

Weight budgets regenerated for the three intentionally grown surfaces.

Closes #68

`seams.md` claimed the parallel-execute worktree's fork point is host-owned and not caller-controllable. It is controllable, via the host's `worktree.baseRef`, and the default (`fresh`, which forks from the remote default branch) is the direct cause of the recorded failure where an executor landed 31 commits behind holding neither the phase CONTEXT nor its own `PLAN-2.md`. v1.4.0 restated that claim across several surfaces on the strength of it, so the correction is not confined to one file. ## What changed **The claim, corrected in 8 places.** `seams.md` (the source), `agents/cad-executor.md` (the `<worktree_mode>` *Reason* line only), `cadence-core/references/git.md`, `config.schema.json`, `workflows/config.md`, `METHOD.md`, `branch-decision.mjs`'s runtime reason string, and `.planning/REQUIREMENTS.md` GIT-01. Mentions that make no fork-point or controllability claim were deliberately left alone. **A preflight.** New read-only seam `cadence-core/bin/worktree-base.mjs` resolves the effective `worktree.baseRef` through the real settings cascade, rooted at the main checkout via `git rev-parse --git-common-dir` so it works from inside a worktree. It emits `{ok, baseRef, source, parallelSafe, reason}`, skips a malformed layer rather than dying on it, refuses on an unrecognized value, and never writes. `execute.md`'s `choose_path` gate now requires it and falls back to sequential when the value is `fresh`. **A `/cad-config` offer.** Shows the file first, merges the single key preserving everything else, never touches managed policy, and does nothing if declined. Offered only when `parallelization.enabled` and `use_worktrees` are both on. ## Constraints honoured - The plugin never silently writes a user's settings. It offers. - `cad-executor.md`'s `<worktree_mode>` assertion is untouched and stays. A setting the user can change back is not a guarantee. - Claims are scoped to Claude Code >= 2.1.208, where the behaviour holds. - Inside a worktree, `head` resolves to that worktree's HEAD, and the prose says so. ## Judgment call The issue asked for the preflight in `execute_parallel`. The gate that actually decides parallel-vs-sequential is `choose_path`, so it lives there with a pointer from `execute_parallel`. ## Verification - `node --test cadence-core/bin/*.test.mjs` → 737 pass, 0 fail (10 new in `worktree-base.test.mjs`) - `npx tsc -p tsconfig.ci.json` → exit 0 - `node cadence-core/bin/self-verify.mjs` → `{"ok":true,...,"problems":[]}` Weight budgets regenerated for the three intentionally grown surfaces. Closes #68