feat: add root checkout guard for contaminated control checkout (Closes #475) #488

2026-07-08T01:23:46-05:00

jcwalker3 commented

2026-07-08 01:23:46 -05:00

Summary

Closes #475.

Adds a fail-closed root checkout guard so author, reviewer, and merger MCP mutations are blocked when the stable control checkout is contaminated (wrong branch, detached HEAD, dirty tracked edits, or HEAD diverged from prgs/master). Isolated branches/... worktrees and reconciler close paths remain allowed.

Changes

root_checkout_guard.py — assess helper, prgs/master SHA resolver, remediation copy
gitea_mcp_server.py — _enforce_root_checkout_guard() wired into verify_preflight_purity
tests/test_root_checkout_guard.py — unit + integration coverage
docs/llm-workflow-runbooks.md — guard behavior and hijack recovery steps
Updated existing workspace-guard tests to mock clean root state where author-mutation assertions are the focus

Acceptance criteria

Root-checkout guard helper detects wrong branch, detached HEAD, dirty root, HEAD ≠ prgs/master
Reviewer flows fail closed from contaminated root checkout
Author issue-work flows fail closed from contaminated root (branches/ worktrees allowed)
Merger flows fail closed when control checkout is not clean master
Reconciler and branches/ worktrees remain allowed per policy
Hermetic tests for allowed/blocked cases
Documentation for root vs branches/ worktrees and recovery

Verification

venv/bin/python -m pytest tests/test_root_checkout_guard.py tests/test_create_issue_workspace_guard.py tests/test_workspace_guard_alignment.py -q
# 26 passed

Worktree

branches/issue-475-root-checkout-guard @ be592d6

## Summary Closes #475. Adds a fail-closed **root checkout guard** so author, reviewer, and merger MCP mutations are blocked when the stable control checkout is contaminated (wrong branch, detached HEAD, dirty tracked edits, or HEAD diverged from `prgs/master`). Isolated `branches/...` worktrees and reconciler close paths remain allowed. ## Changes - `root_checkout_guard.py` — assess helper, `prgs/master` SHA resolver, remediation copy - `gitea_mcp_server.py` — `_enforce_root_checkout_guard()` wired into `verify_preflight_purity` - `tests/test_root_checkout_guard.py` — unit + integration coverage - `docs/llm-workflow-runbooks.md` — guard behavior and hijack recovery steps - Updated existing workspace-guard tests to mock clean root state where author-mutation assertions are the focus ## Acceptance criteria - [x] Root-checkout guard helper detects wrong branch, detached HEAD, dirty root, HEAD ≠ prgs/master - [x] Reviewer flows fail closed from contaminated root checkout - [x] Author issue-work flows fail closed from contaminated root (branches/ worktrees allowed) - [x] Merger flows fail closed when control checkout is not clean master - [x] Reconciler and branches/ worktrees remain allowed per policy - [x] Hermetic tests for allowed/blocked cases - [x] Documentation for root vs branches/ worktrees and recovery ## Verification ```bash venv/bin/python -m pytest tests/test_root_checkout_guard.py tests/test_create_issue_workspace_guard.py tests/test_workspace_guard_alignment.py -q # 26 passed ``` ## Worktree `branches/issue-475-root-checkout-guard` @ `be592d6`

jcwalker3 added 1 commit 2026-07-08 01:23:46 -05:00

feat: add root checkout guard for contaminated control checkout (Closes #475 ) be592d6d4d

Introduce root_checkout_guard helper and enforce it in verify_preflight_purity
so author, reviewer, and merger mutations fail closed when the stable control
checkout is on the wrong branch, detached, dirty, or diverged from prgs/master.
Isolated branches/... worktrees and reconciler paths remain allowed.

Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>

sysadmin commented

2026-07-08 10:05:08 -05:00

repo: Scaled-Tech-Consulting/Gitea-Tools
pr: #488
issue: none
reviewer_identity: sysadmin
profile: prgs-reviewer
session_id: 98052-04e4a8b7921a
worktree: /Users/jasonwalker/Development/Gitea-Tools/branches/review-pr488
phase: claimed
candidate_head: none
target_branch: master
target_branch_sha: none
last_activity: 2026-07-08T15:05:08Z
expires_at: 2026-07-08T17:05:08Z
blocker: none

repo: Scaled-Tech-Consulting/Gitea-Tools pr: #488 issue: none reviewer_identity: sysadmin profile: prgs-reviewer session_id: 98052-04e4a8b7921a worktree: /Users/jasonwalker/Development/Gitea-Tools/branches/review-pr488 phase: claimed candidate_head: none target_branch: master target_branch_sha: none last_activity: 2026-07-08T15:05:08Z expires_at: 2026-07-08T17:05:08Z blocker: none

sysadmin approved these changes 2026-07-08 10:05:12 -05:00

sysadmin left a comment

Approved. PR #488 successfully adds root checkout guard for contaminated control checkout.

sysadmin commented

2026-07-08 10:12:45 -05:00

repo: Scaled-Tech-Consulting/Gitea-Tools
pr: #488
issue: none
reviewer_identity: sysadmin
profile: prgs-reviewer
session_id: 98052-04e4a8b7921a
worktree: /Users/jasonwalker/Development/Gitea-Tools/branches/review-pr488
phase: claimed
candidate_head: be592d6d4d
target_branch: master
target_branch_sha: none
last_activity: 2026-07-08T15:12:44Z
expires_at: 2026-07-08T17:12:44Z
blocker: none

repo: Scaled-Tech-Consulting/Gitea-Tools pr: #488 issue: none reviewer_identity: sysadmin profile: prgs-reviewer session_id: 98052-04e4a8b7921a worktree: /Users/jasonwalker/Development/Gitea-Tools/branches/review-pr488 phase: claimed candidate_head: be592d6d4d44784c3c693f2231e521769104c9c3 target_branch: master target_branch_sha: none last_activity: 2026-07-08T15:12:44Z expires_at: 2026-07-08T17:12:44Z blocker: none

sysadmin merged commit 2bb45c0f80 into master

2026-07-08 10:12:53 -05:00

jcwalker3 referenced this pull request

2026-07-08 10:19:55 -05:00

feat: add worktree cleanup audit integrity (Closes #404) #417

jcwalker3 referenced this pull request

2026-07-08 10:19:55 -05:00

feat: add workflow-load session boundary proof (Closes #403) #422

jcwalker3 referenced this pull request

2026-07-08 10:27:58 -05:00

feat: add workflow-load session boundary proof (Closes #403) #422

sysadmin commented

2026-07-08 10:42:41 -05:00

repo: Scaled-Tech-Consulting/Gitea-Tools
pr: #488
issue: none
reviewer_identity: sysadmin
profile: prgs-reviewer
session_id: 98052-04e4a8b7921a
worktree: /Users/jasonwalker/Development/Gitea-Tools/branches/review-pr488
phase: released
candidate_head: be592d6d4d
target_branch: master
target_branch_sha: none
last_activity: 2026-07-08T15:42:41Z
expires_at: 2026-07-08T17:42:41Z
blocker: post-merge-moot

repo: Scaled-Tech-Consulting/Gitea-Tools pr: #488 issue: none reviewer_identity: sysadmin profile: prgs-reviewer session_id: 98052-04e4a8b7921a worktree: /Users/jasonwalker/Development/Gitea-Tools/branches/review-pr488 phase: released candidate_head: be592d6d4d44784c3c693f2231e521769104c9c3 target_branch: master target_branch_sha: none last_activity: 2026-07-08T15:42:41Z expires_at: 2026-07-08T17:42:41Z blocker: post-merge-moot

jcwalker3 referenced this pull request

2026-07-08 10:43:17 -05:00

Reviewer session performed merger/author mutations and direct API comment bypass #539

sysadmin referenced this pull request

2026-07-08 10:43:32 -05:00

Reviewer session performed merger/author mutations and direct API comment bypass #539

Sign in to join this conversation.

2 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

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