fix-bug

/fix-bug — Host-Neutral Systematic Bug-Fix Workflow

Diagnose and fix a reproducible defect through an open PR. The active Claude Code or Codex host is the main agent for this session; there is no permanent main engine.

Apply the shared Startup boundary before the first workflow step. It is the canonical activation, resume, isolation, and setup-failure contract.

0. Resume or Start

1. Read .forge/instructions.md and .forge/rules/, resolve the active host, then run .forge/hooks/lib/workflow-state.sh show (PowerShell: the .ps1 twin). If canonical state is absent or invalid, stop and use the setup/migration path; never reconstruct it ad hoc.
2. If this worktree already has the matching workflow active, use workflow-state.sh checkpoint with the displayed phase and exact next step to record Last active host, then resume that exact next unchecked durable step. If it is inactive, continue only through the deterministic worktree/base preflight below. Forge provides no edit lock: concurrent sessions are allowed, including simultaneous editing; coordinate overlapping writes. If any session mutates the candidate, candidate-bound evidence becomes stale and must be regenerated before certification.
3. Work outside the protected default branch in one isolated physical worktree, reusing an existing prepared native worktree when present. If none exists, use the portable helper where allowed: .forge/hooks/lib/worktree-lifecycle.sh create --kind fix --name <slug> --base <ref-or-sha> (PowerShell: worktree-lifecycle.ps1 -Action Create -Kind fix -Name <slug> -Base <ref-or-sha>). In a fresh host-native worktree, normalize and seed it before activation with .forge/hooks/lib/worktree-lifecycle.sh adopt --kind fix --name <slug> --base <ref-or-sha> --worktree "$PWD" (PowerShell: worktree-lifecycle.ps1 -Action Adopt -Kind fix -Name <slug> -Base <ref-or-sha> -Worktree $PWD.Path). This safely replaces a clean, unpublished host-generated branch name with fix/<slug>; it never renames protected, dirty, shared, or published work. Only in the Forge source checkout, when the installed path is absent, use the tracked hooks/lib/worktree-lifecycle.sh or .ps1. Native creation or adoption is optional only under the shared startup boundary; never create a second worktree for the same-directory handoff.
4. Continue in the current session by default; switch only if the developer chooses to. A session opened in the primary checkout may continue the linked worktree by using it as the working directory for local edits, reviews, verification, approval recording and normal receipt-validating promotion. Before direct commit, push or PR creation, follow Shipping from the current session. Shipping hooks use the host's event cwd; selecting only the tool working directory does not change that hook context. The procedure verifies the exact task locally while preserving native hooks and authorization. The installed adapter declares the current host for reviewer routing. No per-worktree Forge receipt, copied session identity, or hook-trust bypass is required.
5. The helper seeds only ## State (with ### Now cleared), ## Open Questions, and ## Blockers from the primary checkout and writes the exact baseline to .forge/local/.state-seed-snapshot.md. It never seeds workflow, goal, authorization, receipts, evidence, or local memory. The create and adopt actions both seed state. If an inactive native worktree already has both state and its snapshot, adopt preserves them; if only one exists or a workflow is active, stop rather than guessing or overwriting it.
6. In the target worktree, run workflow-state.sh show and resolve the intended base ref. If state is inactive, invoke .forge/hooks/lib/workflow-state.sh activate --host <claude|codex> --workflow fix-bug --task <slug> --base-ref <ref-or-sha> --phase diagnosis --next-step 'reproduce the symptom' before any discretionary investigation or tracked mutation. On Windows, use the .ps1 twin. The helper resolves and freezes the base SHA. Reuse an already-recorded base for an adopted active worktree; when ancestry is ambiguous, require an explicit base before activation. Never recompute from a later-moving default branch.
7. Replace the active workflow checklist with: