Module worktree 

Isolation and checkpoints.

speccoder works in a git worktree on speccoder/<feature> under its own state directory, so the user’s checkout is never touched. A checkpoint is a git tree object of the whole working tree (tracked and untracked, not ignored), written through a temporary index: HEAD, the index and refs never move. Restoring a checkpoint rewrites only the paths that differ.

Structs

Artifacts

Spec Kit paths a worktree must contain.

Change

One changed path (repository-relative).

Checkpoint

A snapshot of a working tree: a git tree object id.

Leftovers

What checks leave behind in dir that git does not know: build output .gitignore does not list (target/, node_modules/, caches), and lockfiles never committed. No one’s edits — the setup’s gaps.

Refusal

Why speccoder will not work in a worktree here.

Scratch

A detached worktree of a checkout’s HEAD for one check (the review’s red check): never the person’s checkout, never the feature’s worktree. Removed when dropped — on every way out.

Worktree

A worktree speccoder works in.

Enums

ChangeKind

What happened to a path between two checkpoints.

Constants

LOCKFILES

Lockfiles a toolchain writes when the repository has none committed.

SETUP

What the checks run with besides the spec: a change in the checkout reaches the feature’s branch before a run.

Functions

build_output

The build output a check’s toolchain writes into the tree it runs in.

checkpoint

Snapshots the working tree of dir. tmp holds the temporary index (inside speccoder’s state directory).

diff

Paths that differ from from to to.

ensure_lane

A fresh lane worktree for lane of feature, started at start (the feature branch’s tip). A lane left behind is replaced: lanes are speccoder’s scratch space; their work reaches the feature branch only by merging.

ensure_worktree

Creates or reuses the worktree for feature.

files

Every file path in a checkpoint.

keep_ticks

theirs with every checkbox ours ticked ticked too, where the line’s words are the same.

lane_branch

The branch of a lane: one task of feature run in parallel.

leftovers

Leftovers in dir.

only_ticked

Whether ours is base with boxes ticked and nothing else changed.

patch

The textual diff between two checkpoints, without context lines.

project_state_dir

A project’s directory under the state dir: per git repository when the project is in one (shared by its worktrees), else per canonical path.

remove_lane

Removes lane’s worktree and branch, if there are any.

repo_state_dir

A repository’s directory under the state dir, keyed by its canonical common git directory (shared by all of its worktrees).

require_clean

Refuses when the working tree has any uncommitted change (for in-place mode).

restore

Makes the working tree of dir equal to target: differing paths are rewritten from the checkpoint, paths the checkpoint lacks are removed. HEAD, the index and refs are not touched. Returns what changed.

scratch

A scratch worktree of checkout’s HEAD under under.

state_dir

speccoder’s state directory: $SPECCODER_STATE_DIR, else $XDG_STATE_HOME/speccoder, else ~/.local/state/speccoder.

worktree_for

The worktree checked out on branch, if any.