Scaled-Tech-Consulting/Gitea-Tools
2
0
Fork 0
Code Issues 6 Pull Requests 2 Actions Packages Projects Releases Wiki Activity

Complete isolated-worktree helpers (worktree-review, worktree-clean, tests) #39

New Issue
Closed
opened 2026-07-02 01:42:56 -05:00 by jcwalker3 · 2 comments
jcwalker3 commented 2026-07-02 01:42:56 -05:00
Owner
Copy Link
Copy Source

Problem

LLMs should not do implementation or review work in the main repository checkout. Dirty work from one issue can block unrelated work and risks overwriting/contaminating another LLM's changes.

Goal

All issue work happens in isolated branch worktrees under an ignored branches/ directory, so multiple LLMs can work/review concurrently without blocking each other.

Required behavior

  1. Standard ignored worktree dir: branches/.
  2. Add branches/ to .gitignore.
  3. Document the rule: main checkout = orchestration/status only; implementation work in branches/<branch-name>/; review work in a separate review worktree; no LLM edits another issue's branch folder unless assigned; branch folders removed only after PR merge/close + explicit cleanup.
  4. Helper scripts: scripts/worktree-start, scripts/worktree-review, scripts/worktree-clean.
  5. Helpers: fetch/prune first; create branch-specific worktrees under branches/; branch from latest remote master; refuse to overwrite an existing worktree; print the created path; delete nothing unless cleanup is explicitly requested.

Example

git fetch prgs --prune
git worktree add -b fix/issue-123-example branches/fix-issue-123-example prgs/master
cd branches/fix-issue-123-example

Cleanup after merge:

git fetch prgs --prune
git worktree remove branches/fix-issue-123-example
git branch -d fix/issue-123-example

Acceptance criteria

  • branches/ ignored by git.
  • Runbooks require isolated worktrees for implementation + review.
  • Dirty work in one issue no longer blocks unrelated work.
  • Cleanup rules documented.
  • No unrelated local artifacts touched.
  • bash -n on new scripts, full pytest, git diff --check pass.

Non-goals

No change to MCP runtime, Gitea API operations, credential storage, or the canonical profile model.

## Problem LLMs should not do implementation or review work in the main repository checkout. Dirty work from one issue can block unrelated work and risks overwriting/contaminating another LLM's changes. ## Goal All issue work happens in isolated branch worktrees under an ignored `branches/` directory, so multiple LLMs can work/review concurrently without blocking each other. ## Required behavior 1. Standard ignored worktree dir: `branches/`. 2. Add `branches/` to `.gitignore`. 3. Document the rule: main checkout = orchestration/status only; implementation work in `branches/<branch-name>/`; review work in a separate review worktree; no LLM edits another issue's branch folder unless assigned; branch folders removed only after PR merge/close + explicit cleanup. 4. Helper scripts: `scripts/worktree-start`, `scripts/worktree-review`, `scripts/worktree-clean`. 5. Helpers: fetch/prune first; create branch-specific worktrees under `branches/`; branch from latest remote `master`; refuse to overwrite an existing worktree; print the created path; delete nothing unless cleanup is explicitly requested. ## Example ```bash git fetch prgs --prune git worktree add -b fix/issue-123-example branches/fix-issue-123-example prgs/master cd branches/fix-issue-123-example ``` Cleanup after merge: ```bash git fetch prgs --prune git worktree remove branches/fix-issue-123-example git branch -d fix/issue-123-example ``` ## Acceptance criteria - `branches/` ignored by git. - Runbooks require isolated worktrees for implementation + review. - Dirty work in one issue no longer blocks unrelated work. - Cleanup rules documented. - No unrelated local artifacts touched. - `bash -n` on new scripts, full pytest, `git diff --check` pass. ## Non-goals No change to MCP runtime, Gitea API operations, credential storage, or the canonical profile model.
jcwalker3 added the status:in-progress label 2026-07-02 01:43:06 -05:00
jcwalker3 commented 2026-07-02 01:45:00 -05:00
Author
Owner
Copy Link
Copy Source

Duplicate of #38 (same task, already in-progress with a pushed branch docs/issue-38-worktree-standard). Closing; completing the work under #38.

Duplicate of #38 (same task, already in-progress with a pushed branch `docs/issue-38-worktree-standard`). Closing; completing the work under #38.
jcwalker3 removed the status:in-progress label 2026-07-02 01:45:01 -05:00
jcwalker3 changed title from Standardize isolated branch worktrees for LLM work to Complete isolated-worktree helpers (worktree-review, worktree-clean, tests) 2026-07-02 01:52:16 -05:00
jcwalker3 added the status:in-progress label 2026-07-02 01:52:17 -05:00
jcwalker3 commented 2026-07-02 01:52:17 -05:00
Author
Owner
Copy Link
Copy Source

Reopened + repurposed. #38 merged only the partial standard (branches/ gitignore + runbook + scripts/worktree-start) into master (7e8256c). This issue tracks the remainder of the acceptance criteria: scripts/worktree-review, scripts/worktree-clean, and tests. Branch: feat/issue-39-worktree-helpers from master.

Note: the #38 branch worktree under branches/ was removed by external cleanup mid-task; completing on a normal branch in the main checkout.

Reopened + repurposed. #38 merged only the partial standard (`branches/` gitignore + runbook + `scripts/worktree-start`) into master (7e8256c). This issue tracks the remainder of the acceptance criteria: `scripts/worktree-review`, `scripts/worktree-clean`, and tests. Branch: `feat/issue-39-worktree-helpers` from master. Note: the #38 branch worktree under `branches/` was removed by external cleanup mid-task; completing on a normal branch in the main checkout.
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
bug
chore
documentation
Docs / runbooks
 gitea
Gitea MCP workflow
 important
mcp
MCP server / tooling
 mutating
Mutating action; requires gating
 nice-to-have
read-only
Read-only, no mutation
 roadmap
Roadmap / umbrella issue
 security
Security / trust boundary
 status:in-progress
Issue is being worked on
No Label status:in-progress
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
jcwalker3 sysadmin
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: Scaled-Tech-Consulting/Gitea-Tools#39
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?