Enforce branches-only worktrees for all LLM task mutations #274

New Issue

2026-07-06T13:03:11-05:00

jcwalker3 commented

2026-07-06 13:03:11 -05:00

LLMs must never perform issue, PR, feature, bugfix, review-fix, or implementation work directly in the main project checkout.

This rule applies to every repository/project, not only Gitea-Tools.

The main project folder is the stable control checkout. It must remain on the project’s configured stable branch, normally master, main, or dev. It should only be updated after PRs are merged or when explicitly performing control-checkout maintenance.

All LLM task work must happen in an isolated worktree under that project’s branches/ directory.

Examples:

/project-root/                  # stable control checkout: master/main/dev only
/project-root/branches/task-a/  # allowed task worktree
/project-root/branches/task-b/  # allowed task worktree

Required rule:

Before any mutation, the LLM must prove it is working inside the project’s branches/ directory.
If not inside branches/, mutation is forbidden.

Mutation includes, but is not limited to:

editing files
creating files
deleting files
running formatters that write files
running tests that generate or modify files
changing branches
committing
rebasing
merging
applying patches
resolving conflicts
creating PR branches
fixing review comments
preparing merge cleanup
modifying MCP/server/config files
running cleanup tools

Allowed operations in the main checkout:

Read-only inspection.
Checking status.
Fetching from remotes.
Updating the stable checkout after a PR has already merged.
Creating or locating an isolated worktree under branches/.
Explicit control-checkout repair when the user specifically asks to repair the main checkout.

Hard requirements:

Every LLM session must identify:
- project root
- current working directory
- stable branch for the main checkout
- intended task branch
- intended branches/ worktree path
If the current working directory is the project root and not inside branches/, the LLM must stop before mutation.
If the main checkout is on a task branch, the LLM must stop and report that the control checkout has drifted.
If the main checkout is dirty, the LLM must stop and produce a repair handoff.
If a branches/ worktree does not exist for the task, the LLM must create one before doing work.
If the LLM cannot prove it is inside branches/, it must not mutate anything.
PR review, review-fix, merge-prep, conflict resolution, and issue implementation all require a branches/ worktree.
No LLM may treat “small fix,” “quick edit,” “just one file,” “documentation only,” “test only,” “cleanup only,” or “emergency” as an exception.
Final reports and handoffs must include the actual worktree path used.
Any tool or prompt that allows mutation outside branches/ is considered unsafe and must be fixed.

Implementation requirements:

Add a preflight check that detects whether the current path is inside the repository’s branches/ directory.
Add a fail-closed guard before mutation tools.
Add prompt/template language requiring branches-only work.
Add tests for:
- mutation attempted from project root
- mutation attempted from stable checkout
- mutation attempted from wrong sibling directory
- mutation allowed inside branches/<task-worktree>
- main checkout dirty state
- main checkout on task branch
- final report missing worktree path

Acceptance criteria:

LLMs cannot edit, commit, test-write, merge, rebase, or cleanup from the main project checkout.
Main checkout remains on master, main, or dev, depending on project configuration.
All task work happens under branches/.
Any attempted mutation outside branches/ fails before the command runs.
The failure message tells the LLM to create or switch to a branches/ worktree.
Every handoff/final report includes the worktree path.
This rule applies globally across projects, not only one repository.

LLMs must never perform issue, PR, feature, bugfix, review-fix, or implementation work directly in the main project checkout. This rule applies to every repository/project, not only Gitea-Tools. The main project folder is the stable control checkout. It must remain on the project’s configured stable branch, normally `master`, `main`, or `dev`. It should only be updated after PRs are merged or when explicitly performing control-checkout maintenance. All LLM task work must happen in an isolated worktree under that project’s `branches/` directory. Examples: ```text /project-root/ # stable control checkout: master/main/dev only /project-root/branches/task-a/ # allowed task worktree /project-root/branches/task-b/ # allowed task worktree ``` Required rule: ```text Before any mutation, the LLM must prove it is working inside the project’s branches/ directory. If not inside branches/, mutation is forbidden. ``` Mutation includes, but is not limited to: * editing files * creating files * deleting files * running formatters that write files * running tests that generate or modify files * changing branches * committing * rebasing * merging * applying patches * resolving conflicts * creating PR branches * fixing review comments * preparing merge cleanup * modifying MCP/server/config files * running cleanup tools Allowed operations in the main checkout: 1. Read-only inspection. 2. Checking status. 3. Fetching from remotes. 4. Updating the stable checkout after a PR has already merged. 5. Creating or locating an isolated worktree under `branches/`. 6. Explicit control-checkout repair when the user specifically asks to repair the main checkout. Hard requirements: 1. Every LLM session must identify: * project root * current working directory * stable branch for the main checkout * intended task branch * intended `branches/` worktree path 2. If the current working directory is the project root and not inside `branches/`, the LLM must stop before mutation. 3. If the main checkout is on a task branch, the LLM must stop and report that the control checkout has drifted. 4. If the main checkout is dirty, the LLM must stop and produce a repair handoff. 5. If a `branches/` worktree does not exist for the task, the LLM must create one before doing work. 6. If the LLM cannot prove it is inside `branches/`, it must not mutate anything. 7. PR review, review-fix, merge-prep, conflict resolution, and issue implementation all require a `branches/` worktree. 8. No LLM may treat “small fix,” “quick edit,” “just one file,” “documentation only,” “test only,” “cleanup only,” or “emergency” as an exception. 9. Final reports and handoffs must include the actual worktree path used. 10. Any tool or prompt that allows mutation outside `branches/` is considered unsafe and must be fixed. Implementation requirements: * Add a preflight check that detects whether the current path is inside the repository’s `branches/` directory. * Add a fail-closed guard before mutation tools. * Add prompt/template language requiring branches-only work. * Add tests for: * mutation attempted from project root * mutation attempted from stable checkout * mutation attempted from wrong sibling directory * mutation allowed inside `branches/<task-worktree>` * main checkout dirty state * main checkout on task branch * final report missing worktree path Acceptance criteria: * LLMs cannot edit, commit, test-write, merge, rebase, or cleanup from the main project checkout. * Main checkout remains on `master`, `main`, or `dev`, depending on project configuration. * All task work happens under `branches/`. * Any attempted mutation outside `branches/` fails before the command runs. * The failure message tells the LLM to create or switch to a `branches/` worktree. * Every handoff/final report includes the worktree path. * This rule applies globally across projects, not only one repository.

jcwalker3 added the status:in-progress label 2026-07-07 04:43:33 -05:00

jcwalker3 referenced this issue from a commit

2026-07-07 04:45:01 -05:00

feat: enforce branches-only author mutation worktree guard (Closes #274)

jcwalker3 commented

2026-07-07 04:45:04 -05:00

Issue claim heartbeat

kind: progress
issue: Enforce branches-only worktrees for all LLM task mutations (#274)
branch: feat/issue-274-branches-only-worktrees
phase: pr-opened
profile: prgs-author
pr: pending
blocker: none
next_action: await review

**Issue claim heartbeat** - kind: progress - issue: #274 - branch: feat/issue-274-branches-only-worktrees - phase: pr-opened - profile: prgs-author - pr: pending - blocker: none - next_action: await review

jcwalker3 referenced a pull request that will close this issue

2026-07-07 04:47:11 -05:00

feat: enforce branches-only author mutation worktree guard (Closes #274) #374

jcwalker3 commented

2026-07-07 04:47:31 -05:00

Progress update

PR opened: #374 — feat/issue-274-branches-only-worktrees → master

Commit: 6779d90 — branches-only author mutation worktree guard
Tests: test_author_mutation_worktree.py, preflight integration, issue write gates (all passing)
PR mergeable: yes

Ready for review.

**Progress update** PR opened: **#374** — `feat/issue-274-branches-only-worktrees` → `master` - Commit: `6779d90` — branches-only author mutation worktree guard - Tests: `test_author_mutation_worktree.py`, preflight integration, issue write gates (all passing) - PR mergeable: yes Ready for review.

jcwalker3 referenced this issue from a commit

2026-07-07 09:31:28 -05:00

fix: resolve conflicts for PR #374

sysadmin closed this issue

2026-07-07 09:33:19 -05:00

sysadmin removed the status:in-progress label 2026-07-07 09:33:20 -05:00

sysadmin referenced this issue from a commit

2026-07-07 09:33:20 -05:00

Merge pull request 'feat: enforce branches-only author mutation worktree guard (Closes #274)' (#374) from feat/issue-274-branches-only-worktrees into master