Add hard guard preventing LLM sessions from moving the root checkout away from master #475

New Issue

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

jcwalker3 commented

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

Problem

The main project root checkout was moved away from master by an LLM session. The root checkout is supposed to be the stable control checkout on master/prgs/master. Author/reviewer work must happen in isolated branches/... worktrees. When the root checkout is hijacked, later sessions misread queue state, miss files expected on master, run tests from the wrong base, and risk contaminating unrelated PRs.

Required Behavior

The project root checkout must remain on master and fast-forwarded to prgs/master.
Author/reviewer work must happen only in isolated worktrees under branches/... or another approved worktree path.
Tooling must fail closed if a session attempts review/author/merge work directly from the root checkout while it is not on master.
Tooling must provide a clear remediation message:
“Root checkout is not on master. Preserve state, switch root back to master, and use scripts/worktree-review or the sanctioned issue worktree flow.”

Acceptance Criteria

Root-checkout guard helper: Add a helper that detects:
- current path is the repository root
- current branch is not master, or HEAD differs from prgs/master when a fresh fetch is available
- dirty root checkout before role work starts
Reviewer flows fail closed: Reviewer flows must fail closed if run from the contaminated root checkout.
Author issue-work flows fail closed: Author issue-work flows must fail closed if they would mutate the root checkout instead of an issue worktree.
Merge flows fail closed: Merge flows must fail closed if root checkout is not clean master/prgs/master before merge preflight.
scripts/worktree-review continues to work: worktree-review continues to create isolated review worktrees and never changes the root checkout branch.
Hermetic tests: Add tests covering:
- root on master clean: allowed for control operations
- root on feature branch: blocked
- root detached at PR head: blocked
- root dirty: blocked
- isolated branches/... worktree: allowed
Documentation: Add docs explaining:
- root checkout = stable control checkout
- branches/... = disposable role worktrees
- recovery process for root checkout hijack

Non-Goals

Do not delete rescue branches.
Do not auto-reset --hard.
Do not silently stash user work.
Do not bypass MCP role/capability rules.

## Problem The main project root checkout was moved away from master by an LLM session. The root checkout is supposed to be the stable control checkout on master/prgs/master. Author/reviewer work must happen in isolated branches/... worktrees. When the root checkout is hijacked, later sessions misread queue state, miss files expected on master, run tests from the wrong base, and risk contaminating unrelated PRs. ## Required Behavior - The project root checkout must remain on master and fast-forwarded to prgs/master. - Author/reviewer work must happen only in isolated worktrees under branches/... or another approved worktree path. - Tooling must fail closed if a session attempts review/author/merge work directly from the root checkout while it is not on master. - Tooling must provide a clear remediation message: “Root checkout is not on master. Preserve state, switch root back to master, and use scripts/worktree-review or the sanctioned issue worktree flow.” ## Acceptance Criteria 1. **Root-checkout guard helper**: Add a helper that detects: - current path is the repository root - current branch is not master, or HEAD differs from prgs/master when a fresh fetch is available - dirty root checkout before role work starts 2. **Reviewer flows fail closed**: Reviewer flows must fail closed if run from the contaminated root checkout. 3. **Author issue-work flows fail closed**: Author issue-work flows must fail closed if they would mutate the root checkout instead of an issue worktree. 4. **Merge flows fail closed**: Merge flows must fail closed if root checkout is not clean master/prgs/master before merge preflight. 5. **scripts/worktree-review continues to work**: worktree-review continues to create isolated review worktrees and never changes the root checkout branch. 6. **Hermetic tests**: Add tests covering: - root on master clean: allowed for control operations - root on feature branch: blocked - root detached at PR head: blocked - root dirty: blocked - isolated branches/... worktree: allowed 7. **Documentation**: Add docs explaining: - root checkout = stable control checkout - branches/... = disposable role worktrees - recovery process for root checkout hijack ## Non-Goals - Do not delete rescue branches. - Do not auto-reset --hard. - Do not silently stash user work. - Do not bypass MCP role/capability rules.

sysadmin commented

2026-07-08 00:40:13 -05:00

Update: Detailed Root Checkout Stability Policy & Acceptance Criteria

To address recurring incidents where LLM sessions make edits or apply patches in the main root checkout, we are updating the acceptance criteria for this issue to ensure strict guardrails are enforced.

Updated Policy Requirements:

Stable Root Checkout: The main root checkout must stay completely clean, remain on master tracking prgs/master, and contain no local-only commits.
No Root Edits: No author edits, reviewer edits, commits, rebases, merges, patch application, or test-driven modifications may happen in the root checkout.
Isolated Worktrees: All work that can modify files (both authoring and reviewing) must happen inside an isolated worktree under branches/.
Fail-Closed Diagnostics: If root is dirty or ahead/behind unexpectedly, the session must stop immediately and report cleanup/remediation steps instead of continuing.

Confirmed Acceptance Criteria:

Purity Preflight Guard: Add or update a preflight guard that detects when the root checkout is dirty, ahead of prgs/master, detached, or on the wrong branch.
Workflow Fail-Closed: The guard must fail closed for author/reviewer/merger workflows that would edit files or create commits.
Remediation Guidance: The guard must instruct the LLM to create/use a branches/<task> worktree instead.
Obvious Worktree Paths: Existing worktree helper scripts must make the correct path obvious and hard to bypass.
Review Isolated Validation: Reviewer workflows must validate in isolated review worktrees under branches/, not in root.
Author Isolated Patching: Author workflows must apply patches and commit only inside issue/PR worktrees under branches/.
Comprehensive Tests: Add tests proving:
- dirty root blocks write workflows.
- root ahead of prgs/master blocks write workflows.
- clean root allows creation of a proper branches/ worktree.
- existing branch worktrees are allowed.
- read-only inventory/status commands are still allowed from root.
Explicit Prompts/Menus: Update docs/menu prompts so every author/reviewer/merger prompt explicitly says: “Do not modify the root checkout. All work happens under branches/.”
Final-Report Requirements: Add a final-report requirement proving the root checkout was not modified (or if root was already dirty at start, prove no additional root changes were made and report cleanup needed).
Linkages: Linked to the current issue #475 (reused).

### Update: Detailed Root Checkout Stability Policy & Acceptance Criteria To address recurring incidents where LLM sessions make edits or apply patches in the main root checkout, we are updating the acceptance criteria for this issue to ensure strict guardrails are enforced. #### Updated Policy Requirements: * **Stable Root Checkout:** The main root checkout must stay completely clean, remain on `master` tracking `prgs/master`, and contain no local-only commits. * **No Root Edits:** No author edits, reviewer edits, commits, rebases, merges, patch application, or test-driven modifications may happen in the root checkout. * **Isolated Worktrees:** All work that can modify files (both authoring and reviewing) must happen inside an isolated worktree under `branches/`. * **Fail-Closed Diagnostics:** If root is dirty or ahead/behind unexpectedly, the session must stop immediately and report cleanup/remediation steps instead of continuing. #### Confirmed Acceptance Criteria: 1. **Purity Preflight Guard:** Add or update a preflight guard that detects when the root checkout is dirty, ahead of `prgs/master`, detached, or on the wrong branch. 2. **Workflow Fail-Closed:** The guard must fail closed for author/reviewer/merger workflows that would edit files or create commits. 3. **Remediation Guidance:** The guard must instruct the LLM to create/use a `branches/<task>` worktree instead. 4. **Obvious Worktree Paths:** Existing worktree helper scripts must make the correct path obvious and hard to bypass. 5. **Review Isolated Validation:** Reviewer workflows must validate in isolated review worktrees under `branches/`, not in root. 6. **Author Isolated Patching:** Author workflows must apply patches and commit only inside issue/PR worktrees under `branches/`. 7. **Comprehensive Tests:** Add tests proving: * dirty root blocks write workflows. * root ahead of `prgs/master` blocks write workflows. * clean root allows creation of a proper `branches/` worktree. * existing branch worktrees are allowed. * read-only inventory/status commands are still allowed from root. 8. **Explicit Prompts/Menus:** Update docs/menu prompts so every author/reviewer/merger prompt explicitly says: *“Do not modify the root checkout. All work happens under `branches/`.”* 9. **Final-Report Requirements:** Add a final-report requirement proving the root checkout was not modified (or if root was already dirty at start, prove no additional root changes were made and report cleanup needed). 10. **Linkages:** Linked to the current issue #475 (reused).

jcwalker3 referenced this issue

2026-07-08 00:55:24 -05:00

Add first-class stacked PR support to the author workflow (gitea_create_pr blocked on non-master base) #484

jcwalker3 added the status:in-progress label 2026-07-08 01:21:38 -05:00

jcwalker3 commented

2026-07-08 01:21:39 -05:00

Issue claim heartbeat

kind: claim
issue: Add hard guard preventing LLM sessions from moving the root checkout away from master (#475)
branch: feat/issue-475-root-checkout-guard
phase: claimed
profile: prgs-author
pr: none
blocker: none
next_action: create worktree and begin implementation

**Issue claim heartbeat** - kind: claim - issue: #475 - branch: feat/issue-475-root-checkout-guard - phase: claimed - profile: prgs-author - pr: none - blocker: none - next_action: create worktree and begin implementation

jcwalker3 referenced this issue from a commit

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

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

jcwalker3 referenced a pull request that will close this issue

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

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

jcwalker3 referenced this issue

2026-07-08 01:24:59 -05:00

feat: add first-class stacked PR support to author workflow (Closes #484) #489

jcwalker3 referenced this issue

2026-07-08 02:25:58 -05:00

Reviewer mutation tools must use the active branches worktree, not stale MCP server process root #503