Skip to content

spec(worktree-subsystem): add specification for native worktree subsystem#4677

Merged
bug-ops merged 1 commit into
mainfrom
4655-worktree-baseref-config
May 29, 2026
Merged

spec(worktree-subsystem): add specification for native worktree subsystem#4677
bug-ops merged 1 commit into
mainfrom
4655-worktree-baseref-config

Conversation

@bug-ops

@bug-ops bug-ops commented May 29, 2026

Copy link
Copy Markdown
Owner

Summary

Design decisions encoded

C1 — cwd isolation (MVP: Constrain, don't isolate):

  • INV-1: All worktree-attached runs serialized via a process-global CwdGuard mutex; non-worktree agents quiesced while held
  • INV-2: Process cwd saved/restored (RAII) around agent run; restore happens BEFORE git worktree remove
  • INV-3: set_working_directory in disallowed_tools for every worktree agent
  • INV-4: Worktree creation failure aborts that agent's spawn — no silent fallback

Config schema:

[worktree]
enabled = false
base_ref = "head"          # "fresh" | "head"
default_branch = "main"
root = ".claude/worktrees"
branch_prefix = "agent/"
prune_branch_on_remove = false
cleanup_on_completion = true

Deferred:

Architecture

New crate zeph-worktree (~930 LOC, 5 phases per plan.md). Integration with zeph-subagent, zeph-config, zeph-core.

Test plan

  • All spec files validate (fy validate)
  • BRD → SRS → spec → tasks traceability verified by reviewer
  • INV-1..INV-4, M4, A1/A2, S2/S3, D1/D2 markers confirmed present in spec.md
  • tasks.md acceptance criteria reviewed (16 tasks, concrete assertions)

Closes #4655

@bug-ops bug-ops added enhancement New feature or request P3 Research — medium-high complexity labels May 29, 2026
@github-actions github-actions Bot added size/XL Extra large PR (500+ lines) documentation Improvements or additions to documentation labels May 29, 2026
…stem

Produces the full spec package (BRD/SRS/NFR/spec/plan/tasks) for the
worktree subsystem required by issue #4655. Key design decisions:

- New zeph-worktree crate with WorktreeManager/WorktreeHandle/GitRunner
- worktree.base_ref: fresh|head config (TOML [worktree] section)
- CwdGuard mutex for in-process cwd isolation (MVP: concurrency-1)
- Hard invariants: INV-1..INV-4 (cwd save/restore, disallow
  set_working_directory, no silent fallback on create failure)
- Teardown ordering: restore cwd -> release guard -> git worktree remove
- Deferred: cwd-threading (D1), bgIsolation child-process (D2, #4656)

Closes #4655.
@bug-ops bug-ops force-pushed the 4655-worktree-baseref-config branch from 29f4fcd to eaa0769 Compare May 29, 2026 20:47
@bug-ops bug-ops merged commit 55af0ff into main May 29, 2026
20 checks passed
@bug-ops bug-ops deleted the 4655-worktree-baseref-config branch May 29, 2026 20:48
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation enhancement New feature or request P3 Research — medium-high complexity size/XL Extra large PR (500+ lines)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

feat(subagent): worktree.baseRef config — branch from origin/<default> or local HEAD

1 participant