docs: standardize isolated LLM worktrees (#38) #40

2026-07-02T01:44:31-05:00

jcwalker3 commented

2026-07-02 01:44:31 -05:00

Closes #38.

Summary

Standardizes isolated branch worktrees for LLM implementation and review work.

Changes

Adds branches/ to .gitignore as the standard local branch-worktree folder.
Adds scripts/worktree-start, a narrow helper that:
- fetches/prunes prgs
- creates branch-specific worktrees under branches/
- branches from prgs/master by default
- refuses to reuse an existing branch folder
- supports --dry-run
- prints the created worktree path
Updates docs/llm-workflow-runbooks.md with a new Branch worktree isolation section.
Documents implementation vs review isolation, orchestration-checkout rules, cleanup rules, and manual equivalent commands.

Validation

bash -n scripts/worktree-start — passed
scripts/worktree-start --dry-run fix/issue-123-example — passed
scripts/worktree-start --dry-run review/pr-123-scope-check prgs/master — passed
Existing-folder refusal check with temporary ignored branches/existing-test — failed closed as intended; temporary folder removed
git diff --check — passed
git check-ignore branches/example — passed
GITEA_TOKEN_DADESCHOOLS=fake-token ../../venv/bin/python -m pytest tests/ -q — 278 passed

Notes

The exact ./venv/bin/python -m pytest tests/ -q command cannot run in a fresh isolated worktree until that worktree has its own ignored venv/; this PR documents that behavior. I used the orchestration checkout venv by explicit path and a fake token env var to avoid depending on private local credential files.
Existing dirty work in fix/issue-36-config-menu-ux and local artifacts .claude/, .codex/, and report.xml were left untouched.

Review/merge

I authored this PR, so I must not self-review or self-merge.

Closes #38. ## Summary Standardizes isolated branch worktrees for LLM implementation and review work. ## Changes - Adds `branches/` to `.gitignore` as the standard local branch-worktree folder. - Adds `scripts/worktree-start`, a narrow helper that: - fetches/prunes `prgs` - creates branch-specific worktrees under `branches/` - branches from `prgs/master` by default - refuses to reuse an existing branch folder - supports `--dry-run` - prints the created worktree path - Updates `docs/llm-workflow-runbooks.md` with a new `Branch worktree isolation` section. - Documents implementation vs review isolation, orchestration-checkout rules, cleanup rules, and manual equivalent commands. ## Validation - `bash -n scripts/worktree-start` — passed - `scripts/worktree-start --dry-run fix/issue-123-example` — passed - `scripts/worktree-start --dry-run review/pr-123-scope-check prgs/master` — passed - Existing-folder refusal check with temporary ignored `branches/existing-test` — failed closed as intended; temporary folder removed - `git diff --check` — passed - `git check-ignore branches/example` — passed - `GITEA_TOKEN_DADESCHOOLS=fake-token ../../venv/bin/python -m pytest tests/ -q` — 278 passed ## Notes - The exact `./venv/bin/python -m pytest tests/ -q` command cannot run in a fresh isolated worktree until that worktree has its own ignored `venv/`; this PR documents that behavior. I used the orchestration checkout venv by explicit path and a fake token env var to avoid depending on private local credential files. - Existing dirty work in `fix/issue-36-config-menu-ux` and local artifacts `.claude/`, `.codex/`, and `report.xml` were left untouched. ## Review/merge I authored this PR, so I must not self-review or self-merge.

jcwalker3 added 1 commit 2026-07-02 01:44:32 -05:00

docs: standardize isolated LLM worktrees (#38 ) 7e8256cfaf

jcwalker3 closed this pull request

2026-07-02 01:49:42 -05:00

jcwalker3 deleted branch docs/issue-38-worktree-standard

2026-07-02 01:49:42 -05:00

Pull request closed

This pull request cannot be reopened because the branch was deleted.

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: Scaled-Tech-Consulting/Gitea-Tools#40