Make issue claim/lock gates compatible with global branches-only worktrees #275

New Issue

2026-07-06T13:34:18-05:00

jcwalker3 commented

2026-07-06 13:34:18 -05:00

The global branches-only worktree rule requires all LLM task mutations to happen inside a session-owned worktree under branches/.

However, the current issue claim/lock gates still require some operations to be performed from the base checkout or assume the main checkout is the active task workspace. This creates an impossible workflow:

The LLM is not allowed to do task work in the main checkout.
The LLM creates a valid task worktree under branches/.
The claim/lock gate rejects the task worktree because it is not on the base branch.
The LLM cannot safely implement the issue because claim/lock failed.

Observed blocker:

gitea_mark_issue(start #274) failed with:

Pre-flight order violation: Workspace file edits occurred before gitea_whoami verification (fail closed). Offending files: mcp_server.py, role_session_router.py
gitea_lock_issue(#274) failed with:

issue lock must be taken from base branch (main/master), not 'feat/issue-274-branches-only-worktrees' (fail closed)

This must be fixed at the gate/tooling level so all LLMs follow the correct workflow automatically.

Required system behavior:

The main project checkout remains stable on master, main, or dev.
All task work happens in branches/<task-worktree>/.
Issue claim/lock must be allowed from a clean, session-owned, base-equivalent worktree under branches/.
Gates must verify base-equivalence by merge-base/content state, not by requiring the literal current branch to be master, main, or dev.
The claim/lock preflight must inspect the active task worktree, not the shared control checkout.
The gate must require live identity/profile/capability checks before claim/lock.
Implementation must remain blocked until claim/lock succeeds.
Dirty-worktree failures must report the exact inspected path and file statuses.
No prompt-only workaround is acceptable; this must be enforced by tooling, tests, and templates.

Acceptance criteria:

A clean task worktree under branches/ can claim and lock an issue before edits.
The main checkout is never required for normal task work.
Claim/lock does not fail merely because the task branch is not named master, main, or dev.
Claim/lock fails closed if the task worktree is dirty before claim.
The error message identifies the exact worktree inspected.
Tests cover project-root rejection, branches-worktree acceptance, dirty-worktree rejection, and base-equivalence validation.
All LLMs are forced through the same workflow without relying on reminders or ad hoc instructions.

Important framing:

This issue is not asking one LLM to work around the current blocker. It is asking for the MCP gates, templates, tests, and enforcement logic to be fixed so the branches-only workflow works correctly for every future LLM.

The global branches-only worktree rule requires all LLM task mutations to happen inside a session-owned worktree under `branches/`. However, the current issue claim/lock gates still require some operations to be performed from the base checkout or assume the main checkout is the active task workspace. This creates an impossible workflow: * The LLM is not allowed to do task work in the main checkout. * The LLM creates a valid task worktree under `branches/`. * The claim/lock gate rejects the task worktree because it is not on the base branch. * The LLM cannot safely implement the issue because claim/lock failed. Observed blocker: * `gitea_mark_issue(start #274)` failed with: `Pre-flight order violation: Workspace file edits occurred before gitea_whoami verification (fail closed). Offending files: mcp_server.py, role_session_router.py` * `gitea_lock_issue(#274)` failed with: `issue lock must be taken from base branch (main/master), not 'feat/issue-274-branches-only-worktrees' (fail closed)` This must be fixed at the gate/tooling level so all LLMs follow the correct workflow automatically. Required system behavior: 1. The main project checkout remains stable on `master`, `main`, or `dev`. 2. All task work happens in `branches/<task-worktree>/`. 3. Issue claim/lock must be allowed from a clean, session-owned, base-equivalent worktree under `branches/`. 4. Gates must verify base-equivalence by merge-base/content state, not by requiring the literal current branch to be `master`, `main`, or `dev`. 5. The claim/lock preflight must inspect the active task worktree, not the shared control checkout. 6. The gate must require live identity/profile/capability checks before claim/lock. 7. Implementation must remain blocked until claim/lock succeeds. 8. Dirty-worktree failures must report the exact inspected path and file statuses. 9. No prompt-only workaround is acceptable; this must be enforced by tooling, tests, and templates. Acceptance criteria: * A clean task worktree under `branches/` can claim and lock an issue before edits. * The main checkout is never required for normal task work. * Claim/lock does not fail merely because the task branch is not named `master`, `main`, or `dev`. * Claim/lock fails closed if the task worktree is dirty before claim. * The error message identifies the exact worktree inspected. * Tests cover project-root rejection, branches-worktree acceptance, dirty-worktree rejection, and base-equivalence validation. * All LLMs are forced through the same workflow without relying on reminders or ad hoc instructions. Important framing: This issue is not asking one LLM to work around the current blocker. It is asking for the MCP gates, templates, tests, and enforcement logic to be fixed so the branches-only workflow works correctly for every future LLM.

jcwalker3 commented

2026-07-06 13:39:32 -05:00

Runtime preflight must inspect the active branches worktree, not the MCP control checkout

Blocked before issue claim, so I did not start implementation.

Target issue selected: #275, Make issue claim/lock gates compatible with global branches-only worktrees.

I created a clean session-owned clone under branches/ for the claim/lock attempt:

/Users/jasonwalker/Development/Gitea-Tools/branches/issue-275-claim-lock-gates

Proof:

Control checkout: /Users/jasonwalker/Development/Gitea-Tools
Control branch: master
Task cwd/root: /Users/jasonwalker/Development/Gitea-Tools/branches/issue-275-claim-lock-gates
Task branch: master
Inside branches/: yes
Task worktree clean and HEAD == origin/master: c1e47a56920655bc1065897db1de9ff7f6add122

Author MCP proof:

Identity: jcwalker3
Profile: prgs-author
mark_issue capability: allowed/current session

Hard blocker:
gitea_get_runtime_context reports preflight_ready=false because the MCP server sees prior edits in the shared control checkout:

Workspace file edits occurred before gitea_whoami verification (offending files: gitea_mcp_server.py, mcp_server.py, role_session_router.py, task_capability_map.py)

Per the rules, implementation must remain blocked until claim/lock succeeds. I did not edit files, commit, push, or create a PR.

## Runtime preflight must inspect the active branches worktree, not the MCP control checkout Blocked before issue claim, so I did not start implementation. Target issue selected: #275, `Make issue claim/lock gates compatible with global branches-only worktrees`. I created a clean session-owned clone under `branches/` for the claim/lock attempt: `/Users/jasonwalker/Development/Gitea-Tools/branches/issue-275-claim-lock-gates` Proof: - Control checkout: `/Users/jasonwalker/Development/Gitea-Tools` - Control branch: `master` - Task cwd/root: `/Users/jasonwalker/Development/Gitea-Tools/branches/issue-275-claim-lock-gates` - Task branch: `master` - Inside `branches/`: yes - Task worktree clean and `HEAD == origin/master`: `c1e47a56920655bc1065897db1de9ff7f6add122` Author MCP proof: - Identity: `jcwalker3` - Profile: `prgs-author` - `mark_issue` capability: allowed/current session Hard blocker: `gitea_get_runtime_context` reports `preflight_ready=false` because the MCP server sees prior edits in the shared control checkout: `Workspace file edits occurred before gitea_whoami verification (offending files: gitea_mcp_server.py, mcp_server.py, role_session_router.py, task_capability_map.py)` Per the rules, implementation must remain blocked until claim/lock succeeds. I did not edit files, commit, push, or create a PR.

jcwalker3 commented

2026-07-06 13:40:42 -05:00

Additional evidence for #275:

A clean session-owned task worktree was created under branches/:

/Users/jasonwalker/Development/Gitea-Tools/branches/issue-275-claim-lock-gates

Proof reported:

Control checkout: /Users/jasonwalker/Development/Gitea-Tools
Control branch: master
Task cwd/root: /Users/jasonwalker/Development/Gitea-Tools/branches/issue-275-claim-lock-gates
Task branch: master
Inside branches/: yes
Task worktree clean and HEAD == origin/master: c1e47a56920655bc1065897db1de9ff7f6add122

Author MCP proof:

Identity: jcwalker3
Profile: prgs-author
mark_issue capability: allowed/current session

Hard blocker:

gitea_get_runtime_context reports preflight_ready=false because the MCP server sees prior edits in the shared control checkout:

Workspace file edits occurred before gitea_whoami verification
offending files: gitea_mcp_server.py, mcp_server.py, role_session_router.py, task_capability_map.py

This proves the claim/lock problem is not only a branch-name check. The runtime preflight is still anchored to the shared control checkout or MCP server process directory instead of the active task worktree.

Required fix:

Runtime preflight must inspect the active task workspace, not the MCP control checkout.
The active workspace path must be explicit, logged, and included in failure messages.
If the active workspace is inside branches/, dirty-state checks must apply to that task worktree.
Dirty files in the control checkout should trigger control-checkout repair mode, but must not falsely block a clean task worktree unless the requested operation is actually control-checkout repair.
gitea_get_runtime_context, gitea_mark_issue, and gitea_lock_issue must all agree on the same workspace root.
Failure messages must include:
- MCP server process root
- active task workspace root
- inspected git root
- dirty files found
- whether those files are in the active task workspace or the control checkout

Acceptance addition for #275:

A clean task worktree under branches/ must not be blocked by dirty files in the shared control checkout. The tool must either inspect the correct task worktree or fail with a clear “workspace root mismatch” diagnostic.

Additional evidence for #275: A clean session-owned task worktree was created under `branches/`: ```text /Users/jasonwalker/Development/Gitea-Tools/branches/issue-275-claim-lock-gates ``` Proof reported: ```text Control checkout: /Users/jasonwalker/Development/Gitea-Tools Control branch: master Task cwd/root: /Users/jasonwalker/Development/Gitea-Tools/branches/issue-275-claim-lock-gates Task branch: master Inside branches/: yes Task worktree clean and HEAD == origin/master: c1e47a56920655bc1065897db1de9ff7f6add122 ``` Author MCP proof: ```text Identity: jcwalker3 Profile: prgs-author mark_issue capability: allowed/current session ``` Hard blocker: ```text gitea_get_runtime_context reports preflight_ready=false because the MCP server sees prior edits in the shared control checkout: Workspace file edits occurred before gitea_whoami verification offending files: gitea_mcp_server.py, mcp_server.py, role_session_router.py, task_capability_map.py ``` This proves the claim/lock problem is not only a branch-name check. The runtime preflight is still anchored to the shared control checkout or MCP server process directory instead of the active task worktree. Required fix: 1. Runtime preflight must inspect the active task workspace, not the MCP control checkout. 2. The active workspace path must be explicit, logged, and included in failure messages. 3. If the active workspace is inside `branches/`, dirty-state checks must apply to that task worktree. 4. Dirty files in the control checkout should trigger control-checkout repair mode, but must not falsely block a clean task worktree unless the requested operation is actually control-checkout repair. 5. `gitea_get_runtime_context`, `gitea_mark_issue`, and `gitea_lock_issue` must all agree on the same workspace root. 6. Failure messages must include: * MCP server process root * active task workspace root * inspected git root * dirty files found * whether those files are in the active task workspace or the control checkout Acceptance addition for #275: A clean task worktree under `branches/` must not be blocked by dirty files in the shared control checkout. The tool must either inspect the correct task worktree or fail with a clear “workspace root mismatch” diagnostic.

jcwalker3 added the status:in-progress label 2026-07-06 13:42:04 -05:00

jcwalker3 referenced this issue from a commit

2026-07-06 13:48:26 -05:00

feat: align claim/lock gates with branches-only worktrees (#275)

jcwalker3 commented

2026-07-06 13:48:37 -05:00

PR opened for branches-only claim/lock gate fix.

Branch: feat/issue-275-claim-lock-branches-worktree
Worktree: branches/issue-275-claim-lock-gates
HEAD: 67e34ba

Independent non-author review needed before merge.

PR opened for branches-only claim/lock gate fix. Branch: `feat/issue-275-claim-lock-branches-worktree` Worktree: `branches/issue-275-claim-lock-gates` HEAD: `67e34ba` Independent non-author review needed before merge.

jcwalker3 referenced a pull request that will close this issue

2026-07-06 13:49:16 -05:00

feat: align claim/lock gates with branches-only worktrees (Closes #275) #280

jcwalker3 referenced this issue from a commit

2026-07-06 13:51:25 -05:00

feat: align claim/lock gates with branches-only worktrees (#275)

jcwalker3 referenced this issue

2026-07-07 01:16:25 -05:00

Reviewer reports must verify linked issue consistency for the selected PR #314

sysadmin closed this issue

2026-07-07 01:39:36 -05:00

sysadmin removed the status:in-progress label 2026-07-07 01:39:37 -05:00