Interactive Issue Execution Worktree Guardrails

---
name: interactive-issue-execution-worktree-guardrails
description: Execute approved GitHub issues in isolated worktrees with interactive Claude Code/Codex runs, while containing agent drift and salvaging progress when provider/runtime problems occur.
triggers:
  - User asks to implement GitHub issue work via tmux or interactive Claude Code
  - Multiple provider lanes are being run in parallel across issue clusters
  - Main checkout is dirty, behind remote, or otherwise unsafe for direct execution
  - Autonomous agent drift or provider quota failures threaten a run
---

# Interactive issue execution worktree guardrails

Use this for approved issue execution waves in `workspace-hub`-style repos when the user wants tmux/interactive Claude Code and/or parallel provider dispatch.

## Core pattern
1. Start from a clean isolation boundary.
   - `git fetch origin`
   - create a dedicated worktree per issue or tightly bounded issue cluster
   - base from `origin/main`
   - do not use the dirty main checkout for implementation
2. Materialize plan approval locally.
   - if the issue is approved by user direction or GitHub label but local `.planning/plan-approved/<issue>.md` is missing, add the approval marker inside the worktree and commit it first
3. Write a prompt file in the worktree.
   - keep the mission bounded
   - list owned paths and forbidden paths explicitly
   - require final validation, commit, push, issue comment, and close when complete
4. Launch the provider in an isolated lane.
   - Claude Code: use tmux + interactive `claude --dangerously-skip-permissions` when explicitly approved by the user
   - Codex: use autonomous `codex exec --dangerously-bypass-approvals-and-sandbox` for bounded doc/report/readiness tasks
   - Gemini: treat as opportunistic; expect quota failures and have fallback lanes ready
5. Monitor and intervene early.
   - capture pane / inspect status frequently
   - if the agent touches forbidden files, revert those files externally immediately and restate scope in the session
6. Salvage instead of restarting from zero.
   - if Claude stalls or drifts repeatedly, switch to deterministic local generation (`execute_code`, focused scripts, or another provider) to finish the bounded deliverable
   - preserve useful artifacts, remove temporary prompt files, then validate and land
7. Rebase before push.
   - multiple parallel lanes move `main`; expect `fetch` + `rebase origin/main` before pushing
8. Close only after verification.
   - confirm landed commit, owned-file-only diff, issue comment with commit hash/artifacts, and issue closure where scope is fully implemented

## Prompt design rules
Include these sections explicitly:
- repo/worktree/branch/issue number
- mission in one sentence
- owned paths
- read-only context paths
- forbidden paths
- required deliverables
- validation minimum
- instruction to remove temporary prompt artifacts before final commit if they are not durable deliverables

## Known failure modes and mitigations

### 1) Claude Code drifts into unrelated files
Observed recurring hazard: `scripts/testing/coverage-results.json` was repeatedly modified during unrelated issue work.

Mitigation:
- declare forbidden paths in the prompt
- monitor early output, not just the final result
- if drift occurs, externally revert the file immediately
- send a corrective instruction in tmux constraining the scope to owned paths only
- verify `git status` before commit shows only expected files

### 2) Provider quota exhaustion
Observed:
- Gemini lanes can fail with HTTP 429 or credit exhaustion
- parallel waves can leave one provider unusable mid-run

Mitigation:
- do not block the whole wave on one provider
- keep a fallback Claude or Codex lane ready for planning/readiness/doc generation
- comment on the issue if a provider-specific run fails so the execution trail remains visible

### 3) Worktree hook / pre-push environment drift
Observed: valid doc-only changes can fail pre-push due to unrelated repo hook environment issues.

Mitigation:
- validate the actual scope independently
- if the failure is clearly unrelated and the user has authorized aggressive execution, `--no-verify` may be acceptable for low-risk doc/report changes
- document that choice in the issue comment

### 3b) Plan-approved worktree still blocks late commits for ignored `.claude/*` runtime paths
Observed in `feat/ecosystem-sync` execution:
- `.planning/plan-approved/<issue>.md` existed locally and was committed
- normal code/test commits passed
- a later commit that added `.claude/cron/...` and `.claude/state/...` files required `git add -f` because those paths were ignored
- the subsequent commit was blocked by the plan gate with `NO APPROVAL` despite the existing marker

Mitigation:
- before starting work that must land files under ignored/runtime directories (especially `.claude/cron/`, `.claude/state/`, other force-added paths), probe repo policy early rather than discovering it at the final commit
- explicitly check both:
  - whether `.gitignore` ignores the intended deliverable path
  - whether the local enforcement hooks treat those paths as implementation requiring a different approval route
- if the path requires `git add -f`, treat that as a risk signal and do a small preflight commit experiment or hook inspection before spending a full execution wave on dependent tasks
- when the hook blocks, stop and escalate; do not use `FORCE_PLAN_GATE=1`, `--no-verify`, or similar bypasses unless the user explicitly authorizes that exact bypass
- preserve the staged tree and report the exact blocked paths, hook message, and marker-file evidence so the user can resolve policy vs plan mismatch quickly

### 4) Agent run becomes unproductive
Mitigation:
- stop the session instead of letting it burn budget
- switch to a deterministic local method (`execute_code`) for machine-generated artifacts such as inventories, manifests, and validation reports
- use the agent again only for review/final polish if needed

### 5) Repo-local wrappers and audit scripts break in worktrees due to inherited environment
Observed:
- repo-local wrappers that trust inherited `WORKSPACE_HUB` can accidentally execute against the dirty main checkout instead of the isolated worktree
- direct/manual script runs can also mis-read config or policy files from the wrong checkout when `WORKSPACE_HUB` points elsewhere

Mitigation:
- for repo-local wrappers, derive repo root from the wrapper/script path (`BASH_SOURCE` / `__file__`) instead of trusting inherited `WORKSPACE_HUB`
- treat environment variables like `WORKSPACE_HUB` as optional overrides only when that is explicitly intended and tested
- add a wrapper test that sets a stale `WORKSPACE_HUB` and verifies dry-run output still points at the worktree-local script path
- when validating a new deterministic script in a worktree, test both:
  - normal dry-run/runtime
  - stale-env dry-run/runtime

### 6) Baseline/delta artifact identity churn hides real changes
Observed in deterministic weekly audit work:
- using absolute checkout/worktree paths in `audit_scope` makes baseline reuse fail across worktrees
- including volatile path lists inside the finding identity key causes path-footprint changes to look like brand-new findings instead of `is_changed`
- carry-forward sections can silently omit unchanged lower-confidence findings unless explicitly reconciled into the markdown/report totals

Mitigation:
- derive a stable audit scope from repo-relative semantics when possible (for example `.claude/skills`) rather than absolute worktree paths
- define finding identity from semantic fields that should survive normal location churn (classification + canonical names), not from volatile path lists
- detect path/canonical-name/classification changes in delta comparison so scope changes are surfaced as changed findings
- ensure carry-forward markdown/report sections reconcile with summary counts, including unchanged non-high-confidence findings that remain active
- if `_core` / `_internal` findings are meant to be informational-only, propagate that flag through every finding path (including leaf-collision findings), not just duplicate-name findings

### 7) Approved issue scope is stale relative to current main / current CI
Observed in worldenergydata #2451 execution:
- the approved issue was based on an earlier failing CI run with three clustered signatures
- on a fresh worktree from current `origin/main`, one planned cluster (benchmark fixture/plugin failure) no longer reproduced when tested under CI-like extras
- two other signatures were still real and worth fixing, but the broader directory still had unrelated pre-existing failures
- PR CI stayed red overall even after the bounded fix, so closure had to rely on proving the original signatures disappeared rather than waiting for a fully green repo

Mitigation:
- before editing, rerun a verification-first precheck on current `origin/main` in the isolated worktree and mirror CI conditions as closely as practical (`--all-extras`, issue-specific test targets, log inspection)
- treat the issue body/old CI run as a hypothesis, not ground truth; narrow scope to the failures that still reproduce on current head
- if a planned cluster no longer reproduces, do not force a speculative fix just to match the old plan; document the non-reproduction and keep the patch bounded to live failures
- when adjacent failures appear outside the approved cluster, open explicit follow-up issues instead of silently absorbing them into the execution issue
- if PR CI remains red for unrelated repo debt, grep the matrix logs for the original signatures and record evidence that those signatures are gone across all relevant jobs
- only declare the issue materially complete when the approved failure signatures are removed or intentionally converted into tracked skips, even if unrelated checks still fail

### 8) Background `claude -p` worktree runs can implement successfully but still be blocked from validation/commenting by repo-local allowlists
Observed in worldenergydata cost-wave execution (#335/#338/#337):
- delegated/subagent launch was not reliable for the parallel wave, so execution switched to direct background `claude -p` runs in isolated worktrees
- Claude finished the code changes, but the repo-local `.claude/settings.json` allowlist blocked commands like `uv run`, `python -m pytest`, `pytest`, and `gh issue comment`
- the worker logs asked for approval to run those commands even though the implementation itself had completed
- closeout still succeeded by running validation and GitHub comments centrally from Hermes after inspecting the worktree diff and worker log

Mitigation:
- for parallel worktree waves, treat background `claude -p` as an implementation engine, not necessarily the authority for final validation or GitHub reporting
- after each worker exits, inspect three things before trusting the run:
  - `git status --short` / changed files in the worktree
  - the worker log for any approval-blocked commands
  - targeted tests run centrally from Hermes in the same worktree
- if the worker was blocked on `pytest`, `uv run`, or `gh`, do not rerun the whole agent immediately; keep the produced diff, validate it centrally, then commit/push/comment from Hermes
- post an issue note when execution ownership changes (for example: delegated worker timed out, switching to direct background Claude; worker could not comment, so closeout was posted centrally)
- verify pre-existing regression blockers explicitly instead of treating them as worker failures; in this run a planned regression target referenced a module absent on current main, so the right outcome was: document blocker, prove it is pre-existing, and keep the issue-scoped patch bounded
- if this allowlist pattern is expected in a repo, prefer a two-layer plan from the start:
  - worker owns code/test-writing inside the isolated worktree
  - Hermes owns final validation, commit/push, and GitHub comments unless the repo settings explicitly allow those commands

### 8b) Parallel approved worktrees can still produce later PR merge conflicts through shared export/barrel files
Observed in worldenergydata cost-wave landing:
- #335, #337, and #338 were executed in separate worktrees and validated independently
- after #335 merged first, #337 became `DIRTY` at PR level because both branches modified `src/worldenergydata/cost/data_collection/__init__.py`
- the original execution wave had serialized #337 after #335 for implementation ownership, but the later PR-merge step still required an explicit rebase onto updated `origin/main`
- resolving the conflict correctly required preserving both surfaces in the barrel/export file, then rerunning a combined targeted suite (`test_disclosure_ingest_contract.py`, `test_linkage.py`, `test_calibration_schema.py`) before force-pushing the rebased branch

Mitigation:
- when parallel/semi-parallel issue branches touch the same package export file, `__init__.py`, registry file, or shared manifest, assume the merge stage may still serialize even if implementation work was isolated
- before merging the second/third PR in a wave, inspect `gh pr view <n> --json mergeStateStatus` and be ready to rebase the branch onto current `origin/main`
- resolve shared export conflicts by composing both validated surfaces, not by picking one side mechanically
- after rebase conflict resolution, rerun a combined targeted validation set that covers:
  - the branch's own new tests
  - the already-merged adjacent boundary tests touched by the shared file
- if the rebased branch was already pushed, use `git push --force-with-lease` and document that the force-push was only to land the conflict-resolved, revalidated branch
- treat PR mergeability as a separate verification gate from worktree-local implementation success

## Verification checklist
- `git status --short` contains only owned files
- no forbidden files remain modified
- temp prompt files are removed unless intentionally part of the deliverable
- outputs numerically reconcile with their authoritative ledgers or sources
- worktree branch rebased onto latest `origin/main`
- push succeeded (or exception documented)
- issue comment includes what landed and the commit hash
- issue closed only if implementation, not planning-only artifacts, actually completed the approved scope

## When to keep issue open
Keep the issue open if the run only produced readiness dossiers, planning artifacts, or partial reconnaissance without the approved implementation landing.

## Good fit
- bounded doc/report reconciliation
- metadata-only sweeps
- readiness dossiers
- governance or portability doc changes

## Bad fit
- large code changes without tests
- issues lacking approval
- mixed-scope waves without clear owned paths