feat: worktree (git) support on storage adapters (fs)

[lsmonki]

Problem

When a project has external workspaces (specs pointing outside the repo root), and those external repos have git worktrees active for different features, switching between contexts requires manually editing `specd.local.yaml` each time to redirect workspace paths.

This affects any project with external workspaces — not just coordinator repos. Concrete configurations where this arises:

• Pure coordinator repo — no code, only manages specs from multiple external repos. Each external repo may have worktrees for different features in flight simultaneously.
• Normal project with external workspaces — a regular repo declares an external workspace pointing to another repo (e.g. `../shared-platform/specd/specs`), and that external repo has a feature worktree active.

In all cases, `specd.yaml` has stable paths pointing to the external repos' main branches. Working against a feature worktree requires either creating a per-feature `specd.local.yaml` (full replacement, expensive to maintain) or manually editing it each time you switch context.

Decision: active worktree state file + adapter-owned detection and substitution

Worktree support is an adapter capability, not a core concern. The fs adapter knows how to list git worktrees and how to substitute paths; an s3 or git-remote adapter would simply not implement the capability. Core never touches paths — it only stores and forwards the active selection to the adapter.

This approach was chosen over named worktree profiles because:

• No prerequisites — named profiles would require a partial-override / extends mechanism for specd.local.yaml first. This approach is self-contained.
• Git is the source of truth — available worktrees are discovered automatically via git worktree list; the user never declares them in specd config.
• Correct layer — worktree logic (path resolution, git metadata) belongs in the fs adapter, not in a config switching mechanism.
• Self-cleaning — stale selections (worktree deleted) are detected and cleared automatically. No profile lifecycle to manage.
• Named bundles are not needed — the only thing profiles would add is grouping multiple workspace selections under a name. That case is covered by calling specd worktree use multiple times, without the added complexity.

Design

Port interface

abstract class SpecsStoragePort {
  // existing methods...

  supportsWorktrees?(): boolean
  listWorktrees?(): Promise<WorktreeInfo[]>
}

The fs adapter implements these by resolving the workspace path to its git repo root and running git worktree list --porcelain. Other adapters leave them unimplemented.

Flow

1. Core reads `.specd/active-worktrees.yaml` (gitignored) and passes each saved selection to the corresponding adapter when constructing it.
2. The adapter applies the selection internally — for fs, this means substituting the repo root in specs.fs.path and codeRoot with the selected worktree root. The relative path within the repo stays the same.
3. CLI calls listWorktrees() on each adapter that supports it, prompts when there is ambiguity and no saved selection, then calls SetActiveWorktree(workspace, worktreePath) — a core use case that writes the selection to the state file.
4. Subsequent commands read the file and pass the selection to the adapter; no prompting.

State file

# .specd/active-worktrees.yaml (gitignored)
workspaces:
  auth: /projects/auth-feature-xyz
  payments: /projects/payments-main

Path substitution (fs adapter internals)

specd.yaml declares:  ../auth/specd/specs
auth repo root:       /projects/auth
selected worktree:    /projects/auth-feature-xyz
resolved path:        /projects/auth-feature-xyz/specd/specs

Core never sees this substitution — it hands the worktree selection to the adapter and the adapter resolves the final path.

Responsibility split

• Core — stores active selections in `.specd/active-worktrees.yaml`. Exposes `SetActiveWorktree(workspace, path)` use case. Passes selections to adapters at construction time.
• fs adapter — implements `listWorktrees()` and applies path substitution internally.
• CLI — calls `listWorktrees()` on each adapter, prompts when ambiguous, calls `SetActiveWorktree`.
• MCP / CI — non-interactive: uses the saved selection if present; falls back to the original `specd.yaml` path (or fails with a clear error) if there is unresolved ambiguity.

Invalidation

If a saved worktree path no longer exists on disk, the adapter detects it at initialization, core warns and clears that entry — falling back to the original path or re-prompting. `specd worktree reset [workspace]` forces re-selection without deleting the worktree.

Precedence

`specd.local.yaml` always wins — if present, `active-worktrees.yaml` is not applied.

CLI surface

New commands

specd worktree list

Lists all workspaces that support worktrees, their available worktrees (from git), and which one is currently active.

specd worktree use <workspace> [worktree]

Sets the active worktree for a workspace. If [worktree] is omitted and multiple are available, prompts interactively. Writes the selection to the state file.

specd worktree reset [workspace]

Clears the active selection for one or all workspaces, triggering re-detection on next command.

Existing commands that should reflect active worktrees

• specd config show — display the resolved path alongside the configured path for any workspace with an active worktree override.
• specd project overview — show a worktree status section: which worktree is active per workspace, whether any selection is stale.
• specd project context — compiled context must reflect the resolved (substituted) paths, not the raw specd.yaml paths.

Related

• `specd.local.yaml` full-replacement constraint (currently no partial overrides)

[lsmonki]

One constraint that seems worth making explicit before implementing this is the difference between read-only external workspaces and editable external workspaces.

For mixed projects (local default workspace + external workspaces), worktree path substitution looks straightforward as long as the external workspaces are readOnly: switching the local repo worktree just changes the anchor directory, and the external read-only workspace paths can be re-resolved relative to that new location.

The hard case starts when an external workspace is editable (owned / shared). At that point the problem is no longer just path substitution; it becomes multi-repo change materialization/orchestration. A single change may need coordinated worktrees, branch lifecycle, cleanup, and recovery across multiple repos.

Because of that, I think we should treat these as two separate modes:

• Mixed local/external projects: external workspaces allowed only as readOnly
• Coordinator / multi-repo mode: the only place where editable external workspaces are allowed, and where future multi-repo worktree orchestration would live

So before full worktree support exists, I would recommend failing validation for editable external workspaces in non-coordinator projects, instead of allowing configs that look valid but cannot be operated safely.

That keeps the current model simple, while leaving a clean path for future coordinator-mode worktree support.

[lsmonki]

Another implementation path that may be worth capturing here: an initial worktree-based solution could avoid most runtime path-substitution logic by materializing the change environment through a generated local config overlay.

Concretely:

• create the main repo worktree for the change
• create any external editable repo worktrees needed for that change
• generate a gitignored specd.local.yaml (or similar generated local variant) inside the change worktree
• use that local overlay to override workspaces.<name>.specs.fs.path, codeRoot, schemas.fs.path, and any other paths that need to point at the materialized worktree locations

That means the active change environment is largely expressed as normal config resolution rather than as a special global worktree-selection mechanism.

This is also why #16 matters here: partial override / extends would let specd generate a very small local overlay instead of duplicating the full specd.yaml. In practice, that could make an initial coordinator/worktree implementation much simpler and easier to debug:

• no need to rewrite the base config
• no need for full runtime path substitution across the app as a first step
• the materialized environment is explicit and physically attached to the change worktree directory
• entering that worktree automatically activates the correct workspace paths

This would not replace future native worktree support/discovery, but it could be a strong first implementation strategy, especially for coordinator-mode multi-repo changes.