sequant 1.5.5 → 1.6.0

package/README.md

@@ -1,410 +1,184 @@
 # Sequant
 
-**Structured AI workflow for GitHub issues.**
+**Workflow automation for [Claude Code](https://claude.ai/code).**
 
-Turn GitHub issues into working code through sequential AI-assisted phases with quality gates.
+Solve GitHub issues with structured phases and quality gates — from issue to merge-ready PR.
 
 [![npm version](https://img.shields.io/npm/v/sequant.svg)](https://www.npmjs.com/package/sequant)
 [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
 
-## Why Sequant?
-
-When using AI coding assistants, work can become scattered and quality inconsistent. Sequant solves this by:
-
-- **Consistent quality** — Every issue goes through the same review gates
-- **Traceable decisions** — Plans and progress documented in GitHub issues
-- **Isolated work** — Git worktrees prevent half-finished features from polluting main
-- **AI-assisted** — Claude Code handles implementation while you review and approve
-
-## How It Works
-
-```
-┌─────────┐    ┌─────────┐    ┌─────────┐    ┌─────────┐
-│  /spec  │───▶│  /exec  │───▶│  /test  │───▶│   /qa   │───▶ Merge
-└─────────┘    └─────────┘    └─────────┘    └─────────┘
-     │              │              │              │
-     ▼              ▼              ▼              ▼
-   Plan          Build          Verify        Review
-  (drafts AC)   (worktree)    (optional)    (vs criteria)
-```
-
-1. **`/spec`** — Reads issue, drafts implementation plan, posts to GitHub for your approval
-2. **`/exec`** — Creates isolated git worktree, implements changes, runs tests
-3. **`/test`** — Optional browser/CLI verification
-4. **`/qa`** — Reviews code against acceptance criteria, suggests fixes
-
 ## Quick Start
 
-### Prerequisites
-
-| Requirement | Check Command | Notes |
-|------------|---------------|-------|
-| [Claude Code](https://claude.ai/code) | `claude --version` | Required |
-| [GitHub CLI](https://cli.github.com/) | `gh auth status` | Required, must be authenticated |
-| Node.js 18+ | `node --version` | Required |
-| Git | `git --version` | Required |
-| [jq](https://jqlang.github.io/jq/) | `jq --version` | Optional, improves hook performance |
-
-> **Note:** Sequant currently requires GitHub for issue tracking. GitLab and Bitbucket support is planned for a future release. See [Platform Requirements](docs/platform-requirements.md) for workarounds if you use a different platform.
-
-### Setup
-
 ```bash
-# Install and initialize in your project
+# In your project directory
 npx sequant init
-
-# Verify installation and prerequisites
-npx sequant doctor
+npx sequant doctor   # Verify setup
 ```
 
-The `doctor` command checks all prerequisites including GitHub CLI authentication.
-
-### First Workflow
+Then in Claude Code:
 
-Open Claude Code in your project, then:
-
-```bash
-/spec 123    # Plan implementation for GitHub issue #123
-/exec 123    # Implement the feature in a worktree
-/qa 123      # Quality review before merge
 ```
-
-> Replace `123` with an actual GitHub issue number from your repository.
-
-## Installation
-
-```bash
-npm install -g sequant
-# or use npx
-npx sequant init
+/fullsolve 123    # Solve issue #123 end-to-end
 ```
 
-## Features
-
-- **🔢 Quantized** - Each issue is an atomic unit of work
-- **🔄 Sequential** - Phases execute in order with gates
-- **🚦 Gated** - Quality checks before progression
-- **🌳 Isolated** - Git worktrees prevent cross-contamination
-- **📦 Stack Adapters** - Pre-configured for Next.js, Rust, Python, Go
-- **🔄 Update-Safe** - Customize without losing updates
+Or step-by-step:
 
-## Optional MCP Integrations
-
-Sequant works fully without any MCP servers, but these optional integrations enhance specific workflows. See the [MCP Integrations Guide](docs/mcp-integrations.md) for detailed setup and troubleshooting.
-
-| MCP Server | Skills | Purpose | Install |
-|------------|--------|---------|---------|
-| [Chrome DevTools](https://github.com/anthropics/anthropic-quickstarts/tree/main/mcp-chrome-devtools) | `/test`, `/testgen`, `/loop` | Browser automation for UI testing | See [setup guide](https://github.com/anthropics/anthropic-quickstarts/tree/main/mcp-chrome-devtools#setup) |
-| [Context7](https://github.com/upstash/context7) | `/exec`, `/fullsolve` | External library documentation lookup | `npx -y @anthropic/mcp-cli add upstash/context7` |
-| [Sequential Thinking](https://github.com/anthropics/anthropic-quickstarts/tree/main/mcp-sequential-thinking) | `/fullsolve` | Complex multi-step reasoning | See [setup guide](https://github.com/anthropics/anthropic-quickstarts/tree/main/mcp-sequential-thinking#setup) |
-
-**What happens without MCPs:**
-- `/test` and `/testgen` fall back to manual testing instructions
-- `/exec` uses codebase search instead of library docs lookup
-- `/fullsolve` uses standard reasoning (no extended thinking)
+```
+/spec 123    # Plan implementation
+/exec 123    # Build in isolated worktree
+/qa 123      # Review before merge
+```
 
-Run `sequant doctor` to check which optional MCPs are configured.
+### Prerequisites
 
-## Commands
+- [Claude Code](https://claude.ai/code) — AI coding assistant
+- [GitHub CLI](https://cli.github.com/) — run `gh auth login`
+- Node.js 18+ and Git
 
-### CLI Commands
+---
 
-```bash
-npx sequant init              # Initialize in your project
-npx sequant update            # Update templates from package
-npx sequant doctor            # Check installation health
-npx sequant status            # Show version and config
-npx sequant run <issues...>   # Execute workflow for issues
-```
+## How It Works
 
-#### Run Command Options
+Sequant adds slash commands to Claude Code that enforce a structured workflow:
 
-```bash
-npx sequant run 123                    # Single issue
-npx sequant run 1 2 3                  # Multiple issues in parallel
-npx sequant run 1 2 3 --sequential     # Run in order
-npx sequant run 123 --phases spec,qa   # Custom phases
-npx sequant run 123 --quality-loop     # Auto-retry on failures
-npx sequant run 123 --dry-run          # Preview without execution
 ```
-
-#### Quality Loop
-
-Quality loop provides automatic fix iterations when phases fail:
-
-```bash
-npx sequant run 123 --quality-loop              # Enable for any issue
-npx sequant run 123 --quality-loop --max-iterations 5  # Custom limit
+┌─────────┐    ┌─────────┐    ┌─────────┐    ┌─────────┐
+│  /spec  │───▶│  /exec  │───▶│  /test  │───▶│   /qa   │───▶ Merge
+└─────────┘    └─────────┘    └─────────┘    └─────────┘
+     │              │              │              │
+     ▼              ▼              ▼              ▼
+   Plan          Build        Verify (UI)     Review
 ```
 
-**How it works:**
-1. Runs phases normally (spec → exec → qa)
-2. If a phase fails, runs `/loop` to fix issues
-3. Re-runs failed phases after fixes
-4. Iterates up to 3 times (default)
-
-**Smart defaults:** Quality loop auto-enables for issues with `complex`, `refactor`, `breaking`, or `major` labels—no flag needed.
+> `/test` is optional — used for UI features when Chrome DevTools MCP is available.
 
-#### Phase Detection
+### Quality Gates
 
-When you run `sequant run`, phases are determined automatically using a three-level detection system:
+Every `/qa` runs automated checks:
 
-1. **Explicit phases** — If you specify `--phases`, those are used
-2. **Spec-driven** — Otherwise, `/spec` runs first and outputs a recommended workflow
-3. **Label-based fallback** — If spec parsing fails, issue labels determine phases
+- **AC Adherence** — Code verified against acceptance criteria
+- **Type Safety** — Detects `any`, `as any`, missing types
+- **Security Scans** — OWASP-style vulnerability detection
+- **Scope Analysis** — Flags changes outside issue scope
 
-**Label-based detection:**
+When checks fail, `/loop` automatically fixes and re-runs (up to 3x).
 
-| Labels | Phases | Notes |
-|--------|--------|-------|
-| `bug`, `fix`, `hotfix`, `patch` | `exec → qa` | Skip spec for simple fixes |
-| `docs`, `documentation`, `readme` | `exec → qa` | Skip spec for docs changes |
-| `ui`, `frontend`, `admin`, `web`, `browser` | `spec → exec → test → qa` | Add browser testing |
-| `complex`, `refactor`, `breaking`, `major` | (default phases) | Enable quality loop |
+---
 
-**Spec-driven detection:**
+## Two Ways to Use
 
-The `/spec` command outputs a recommended workflow that the CLI parses:
+### Interactive (Claude Code)
 
-```markdown
-## Recommended Workflow
+Type commands directly in Claude Code chat:
 
-**Phases:** exec → test → qa
-**Quality Loop:** disabled
-**Reasoning:** UI changes detected, adding browser testing phase
+```
+/fullsolve 123              # Complete pipeline
+/spec 123 → /exec → /qa     # Step by step
 ```
 
-**CLI examples:**
-
-```bash
-# Phases auto-detected (default)
-npx sequant run 123
-
-# Explicit phases (skip auto-detection)
-npx sequant run 123 --phases exec,qa
+### Headless (CLI)
 
-# Disable logging for one run
-npx sequant run 123 --no-log
+Run without Claude Code UI:
 
-# Enable quality loop for complex changes
+```bash
+npx sequant run 123              # Single issue
+npx sequant run 1 2 3            # Batch (parallel)
 npx sequant run 123 --quality-loop
 ```
 
-### Workflow Commands (in Claude Code)
-
-| Command | Phase | Purpose |
-|---------|-------|---------|
-| `/assess` | 0 | Issue triage and status assessment |
-| `/spec` | 1 | Plan implementation vs acceptance criteria |
-| `/exec` | 2 | Implement in feature worktree |
-| `/test` | 2.5 | Browser-based UI testing (optional) |
-| `/verify` | 2.5 | CLI/script verification (optional) |
-| `/qa` | 3 | Code review and quality gate |
-| `/docs` | 4 | Generate feature documentation |
-| `/loop` | * | Fix iteration when tests fail |
-| `/fullsolve` | 1-4 | Complete pipeline in one command |
+---
 
-## Platform Support
-
-| Platform | Status | Notes |
-|----------|--------|-------|
-| macOS | ✅ Tested | Full support with Claude Code, Cursor, VS Code |
-| Linux | ✅ Supported | Bash required for shell scripts |
-| Windows WSL | ✅ Supported | Use WSL2 with bash |
-| Windows Native | ⚠️ Limited | CLI works, but shell scripts require WSL |
-
-### Windows Users
-
-**WSL is recommended** for the full Sequant experience on Windows. Here's why:
-
-| Feature | Native Windows | Windows + WSL |
-|---------|----------------|---------------|
-| CLI commands (`init`, `doctor`, `status`) | ✅ Works | ✅ Works |
-| Workflow hooks (pre-tool, post-tool) | ❌ Requires bash | ✅ Works |
-| Shell scripts (`new-feature.sh`, etc.) | ❌ Requires bash | ✅ Works |
-| Git worktree workflows | ✅ Works | ✅ Works |
-
-**Quick WSL Setup:**
-
-1. Install WSL (run in PowerShell as Administrator): `wsl --install`
-2. Restart your computer when prompted
-3. Open Ubuntu from Start menu and complete setup
-4. Install Node.js: See [NodeSource distributions](https://github.com/nodesource/distributions)
-5. Install GitHub CLI: `apt install gh` then `gh auth login`
-6. Use Sequant: `npx sequant init`
-
-For detailed instructions, see [Microsoft's WSL documentation](https://learn.microsoft.com/en-us/windows/wsl/install).
+## Commands
 
-### Requirements
+### Core Workflow
 
-- **Node.js** 18.0.0 or higher
-- **Git** for worktree support
-- **GitHub CLI** (`gh`) for issue integration — must be authenticated via `gh auth login`
-- **Bash** for shell scripts (included in macOS/Linux, use WSL on Windows)
-- **jq** (optional) for faster JSON parsing in hooks — falls back to grep if not installed
+| Command | Purpose |
+|---------|---------|
+| `/spec` | Plan implementation, draft acceptance criteria |
+| `/exec` | Implement in isolated git worktree |
+| `/test` | Browser-based UI testing (optional) |
+| `/qa` | Code review and quality gate |
 
-### IDE Compatibility
+### Automation
 
-| IDE | Status |
-|-----|--------|
-| Claude Code | ✅ Full support |
-| Cursor | ✅ Supported |
-| VS Code + Copilot | ✅ Supported |
+| Command | Purpose |
+|---------|---------|
+| `/fullsolve` | Complete pipeline in one command |
+| `/solve` | Recommend optimal workflow for issue |
+| `/loop` | Fix iteration when checks fail |
 
-## Stack Support
+### Integration
 
-Sequant auto-detects your project stack and configures appropriate commands:
+| Command | Purpose |
+|---------|---------|
+| `/merger` | Multi-issue integration and merge |
+| `/testgen` | Generate test stubs from spec |
+| `/verify` | CLI/script execution verification |
 
-| Stack | Detection | Test | Build | Lint |
-|-------|-----------|------|-------|------|
-| Next.js | `next.config.*` | `npm test` | `npm run build` | `npm run lint` |
-| Rust | `Cargo.toml` | `cargo test` | `cargo build --release` | `cargo clippy` |
-| Python | `pyproject.toml` | `pytest` | `python -m build` | `ruff check .` |
-| Go | `go.mod` | `go test ./...` | `go build ./...` | `golangci-lint run` |
+### Utilities
 
-## Customization
+| Command | Purpose |
+|---------|---------|
+| `/assess` | Issue triage and status assessment |
+| `/docs` | Generate feature documentation |
+| `/clean` | Repository cleanup |
+| `/security-review` | Deep security analysis |
+| `/reflect` | Workflow improvement analysis |
 
-### Local Overrides
+---
 
-Create files in `.claude/.local/` to override templates without losing updates:
+## CLI Commands
 
+```bash
+npx sequant init              # Initialize in project
+npx sequant update            # Update skill templates
+npx sequant doctor            # Check installation
+npx sequant status            # Show version and config
+npx sequant run <issues...>   # Execute workflow
 ```
-.claude/
-├── skills/           # Package-provided (updated by sequant update)
-├── skills.local/     # Your overrides (never modified)
-├── hooks/            # Package-provided
-├── hooks.local/      # Your overrides
-└── memory/           # Your project context (never modified)
-```
-
-### Constitution
-
-Edit `.claude/memory/constitution.md` to define project-specific principles:
 
-```markdown
-# My Project Constitution
-
-## Core Principles
-1. Always use TypeScript strict mode
-2. Test coverage must exceed 80%
-3. All PRs require security review
-
-## Naming Conventions
-- Components: PascalCase
-- Utilities: camelCase
-- Constants: SCREAMING_SNAKE_CASE
-```
+See [Run Command Options](docs/run-command.md) for advanced usage.
 
-### Settings
+---
 
-Configure `sequant run` defaults in `.sequant/settings.json`:
+## Configuration
 
 ```json
+// .sequant/settings.json
 {
-  "version": "1.0",
   "run": {
-    "logJson": true,
-    "logPath": ".sequant/logs",
-    "autoDetectPhases": true,
-    "timeout": 300,
-    "sequential": false,
     "qualityLoop": false,
-    "maxIterations": 3,
-    "smartTests": true
-  },
-  "agents": {
-    "parallel": false,
-    "model": "haiku"
+    "maxIterations": 3
   }
 }
 ```
 
-#### Run Settings
-
-| Option | Default | Description |
-|--------|---------|-------------|
-| `logJson` | `true` | Enable JSON logging for run sessions |
-| `logPath` | `.sequant/logs` | Directory for log files |
-| `autoDetectPhases` | `true` | Auto-detect phases from labels/spec output |
-| `timeout` | `300` | Timeout per phase in seconds |
-| `sequential` | `false` | Run issues sequentially (vs parallel) |
-| `qualityLoop` | `false` | Enable quality loop by default |
-| `maxIterations` | `3` | Max quality loop iterations |
-| `smartTests` | `true` | Auto-detect test commands |
-
-#### Agent Settings
-
-| Option | Default | Description |
-|--------|---------|-------------|
-| `parallel` | `false` | Run sub-agents in parallel (faster but higher token usage) |
-| `model` | `"haiku"` | Default model for sub-agents (`haiku`, `sonnet`, or `opus`) |
-
-##### Cost vs Speed Trade-offs
-
-Skills like `/qa`, `/merger`, and `/fullsolve` spawn sub-agents for quality checks. The `agents` settings control how these agents execute:
+See [Customization Guide](docs/customization.md) for all options.
 
-| Mode | Token Usage | Speed | Best For |
-|------|-------------|-------|----------|
-| Sequential (`parallel: false`) | 1x (baseline) | Slower | Limited API plans, cost-conscious users |
-| Parallel (`parallel: true`) | ~2-3x | ~50% faster | Unlimited plans, batch operations |
+---
 
-**Override per invocation:**
-
-```bash
-/qa 123 --parallel     # Force parallel (faster)
-/qa 123 --sequential   # Force sequential (cheaper)
-```
-
-CLI flags override settings file values.
+## Platform Support
 
-## Directory Structure
+| Platform | Status |
+|----------|--------|
+| macOS | ✅ Full support |
+| Linux | ✅ Full support |
+| Windows WSL | ✅ Full support |
+| Windows Native | ⚠️ CLI only |
 
-After `sequant init`:
-
-```
-.claude/
-├── skills/              # Workflow commands
-│   ├── spec/SKILL.md
-│   ├── exec/SKILL.md
-│   ├── qa/SKILL.md
-│   └── ...
-├── hooks/               # Pre/post tool hooks
-│   ├── pre-tool.sh
-│   └── post-tool.sh
-├── memory/              # Project context
-│   └── constitution.md
-└── settings.json        # Hooks configuration
-
-.sequant-manifest.json   # Version tracking
-```
+---
 
 ## Documentation
 
-- [Run Command](docs/run-command.md) — Batch execution options
-- [Customization Guide](docs/customization.md) — Override templates safely
-- [MCP Integrations](docs/mcp-integrations.md) — Optional MCP server setup
-- [Platform Requirements](docs/platform-requirements.md) — GitHub dependency and workarounds
-- [Troubleshooting](docs/troubleshooting.md) — Common issues and solutions
-- [Testing Guide](docs/testing.md) — Cross-platform testing matrix
-- [Git Patterns](docs/git-patterns.md) — Worktree and merge workflows
-- [Release Checklist](docs/release-checklist.md) — Pre-release verification
-- Stack Guides: [Next.js](docs/stacks/nextjs.md) | [Rust](docs/stacks/rust.md) | [Python](docs/stacks/python.md) | [Go](docs/stacks/go.md)
-
-## Philosophy
-
-Sequant is built on these principles:
-
-1. **Explicit over implicit** — Every phase has clear inputs and outputs
-2. **Quality gates** — No phase completes without validation
-3. **Isolation** — Work happens in dedicated worktrees
-4. **Traceability** — All decisions recorded in GitHub issues
-5. **Composability** — Use phases individually or combine them
+- [Getting Started](docs/getting-started/installation.md)
+- [Workflow Concepts](docs/concepts/workflow-phases.md)
+- [Run Command](docs/run-command.md)
+- [Customization](docs/customization.md)
+- [Troubleshooting](docs/troubleshooting.md)
 
-## Acknowledgments
+Stack guides: [Next.js](docs/stacks/nextjs.md) · [Rust](docs/stacks/rust.md) · [Python](docs/stacks/python.md) · [Go](docs/stacks/go.md)
 
-Built on ideas from:
-- [Agent Skills](https://agentskills.io) — Open standard for cross-platform skills
-- [BMAD Method](https://github.com/bmad-code-org/BMAD-METHOD) — Update-safe directories
+---
 
 ## License
 

package/dist/src/commands/run.js

@@ -135,6 +135,16 @@ async function ensureWorktree(issueNumber, title, verbose, packageManager) {
     if (verbose) {
         console.log(chalk.gray(`    🌿 Creating worktree for #${issueNumber}...`));
     }
+    // Fetch latest main to ensure worktree starts from fresh baseline
+    if (verbose) {
+        console.log(chalk.gray(`    🔄 Fetching latest main...`));
+    }
+    const fetchResult = spawnSync("git", ["fetch", "origin", "main"], {
+        stdio: "pipe",
+    });
+    if (fetchResult.status !== 0 && verbose) {
+        console.log(chalk.yellow(`    ⚠️  Could not fetch origin/main, using local state`));
+    }
     // Ensure worktrees directory exists
     if (!existsSync(worktreesDir)) {
         spawnSync("mkdir", ["-p", worktreesDir], { stdio: "pipe" });
@@ -148,8 +158,8 @@ async function ensureWorktree(issueNumber, title, verbose, packageManager) {
         });
     }
     else {
-        // Create new branch from main
-        createResult = spawnSync("git", ["worktree", "add", worktreePath, "-b", branch], { stdio: "pipe" });
+        // Create new branch from origin/main (fresh baseline)
+        createResult = spawnSync("git", ["worktree", "add", worktreePath, "-b", branch, "origin/main"], { stdio: "pipe" });
     }
     if (createResult.status !== 0) {
         const error = createResult.stderr.toString();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sequant",
-  "version": "1.5.5",
+  "version": "1.6.0",
   "description": "Quantize your development workflow - Sequential AI phases with quality gates",
   "type": "module",
   "bin": {

package/templates/hooks/pre-tool.sh

@@ -108,6 +108,50 @@ if echo "$TOOL_INPUT" | grep -qE 'git push.*(--force| -f($| ))'; then
     exit 2
 fi
 
+# --- Hard Reset Protection (Issue #85, enhanced) ---
+# Block git reset --hard when there is local work that would be lost:
+# - Unpushed commits on main/master
+# - Uncommitted changes (staged or unstaged)
+# - Unfinished merge in progress
+if echo "$TOOL_INPUT" | grep -qE 'git reset.*(--hard|origin)'; then
+    CURRENT_BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo "")
+    BLOCK_REASONS=""
+    
+    # Check 1: Unpushed commits (only on main/master)
+    if [[ "$CURRENT_BRANCH" == "main" || "$CURRENT_BRANCH" == "master" ]]; then
+        UNPUSHED=$(git log origin/$CURRENT_BRANCH..HEAD --oneline 2>/dev/null | wc -l | tr -d ' ')
+        if [[ "$UNPUSHED" -gt 0 ]]; then
+            BLOCK_REASONS="${BLOCK_REASONS}  - $UNPUSHED unpushed commit(s) on $CURRENT_BRANCH\n"
+        fi
+    fi
+    
+    # Check 2: Uncommitted changes (staged or unstaged)
+    UNCOMMITTED=$(git status --porcelain 2>/dev/null | wc -l | tr -d ' ')
+    if [[ "$UNCOMMITTED" -gt 0 ]]; then
+        BLOCK_REASONS="${BLOCK_REASONS}  - $UNCOMMITTED uncommitted file(s)\n"
+    fi
+    
+    # Check 3: Unfinished merge
+    GIT_DIR=$(git rev-parse --git-dir 2>/dev/null || echo ".git")
+    if [[ -f "$GIT_DIR/MERGE_HEAD" ]]; then
+        BLOCK_REASONS="${BLOCK_REASONS}  - Unfinished merge in progress\n"
+    fi
+    
+    # Block if any reasons found
+    if [[ -n "$BLOCK_REASONS" ]]; then
+        {
+            echo "HOOK_BLOCKED: git reset --hard would lose local work:"
+            echo -e "$BLOCK_REASONS"
+            echo "  Resolve with:"
+            echo "    git push origin $CURRENT_BRANCH  # push commits"
+            echo "    git stash                        # save changes"
+            echo "    git merge --abort                # cancel merge"
+            echo "  Or run directly in terminal (outside Claude Code) to bypass"
+        } | tee -a /tmp/claude-hook.log >&2
+        exit 2
+    fi
+fi
+
 # CI/CD triggers (automation shouldn't trigger more automation)
 if echo "$TOOL_INPUT" | grep -qE 'gh workflow run'; then
     echo "HOOK_BLOCKED: Workflow trigger" | tee -a /tmp/claude-hook.log >&2
@@ -273,22 +317,33 @@ if [[ "$TOOL_NAME" == "Bash" ]] && echo "$TOOL_INPUT" | grep -qE 'git commit'; t
     fi
 fi
 
-# === WORKTREE PATH ENFORCEMENT FOR PARALLEL AGENTS ===
-# When a parallel marker exists with a worktree path, block edits outside that worktree
+# === WORKTREE PATH ENFORCEMENT ===
+# Enforces that file operations stay within the designated worktree
+# Sources for worktree path (in priority order):
+#   1. SEQUANT_WORKTREE env var - set by `sequant run` for isolated issue execution
+#   2. Parallel marker file - for parallel agent execution
 # This prevents agents from accidentally editing the main repo instead of the worktree
-# Marker file format: First line contains the expected worktree path
 if [[ "$TOOL_NAME" == "Edit" || "$TOOL_NAME" == "Write" ]]; then
     EXPECTED_WORKTREE=""
-    for marker in "${PARALLEL_MARKER_PREFIX}"*.marker; do
-        if [[ -f "$marker" ]]; then
-            # Read expected worktree path from marker file (first line)
-            EXPECTED_WORKTREE=$(head -1 "$marker" 2>/dev/null || true)
-            break
-        fi
-    done
+
+    # Priority 1: Check SEQUANT_WORKTREE environment variable (set by sequant run)
+    if [[ -n "${SEQUANT_WORKTREE:-}" ]]; then
+        EXPECTED_WORKTREE="$SEQUANT_WORKTREE"
+    fi
+
+    # Priority 2: Fall back to parallel marker file
+    if [[ -z "$EXPECTED_WORKTREE" ]]; then
+        for marker in "${PARALLEL_MARKER_PREFIX}"*.marker; do
+            if [[ -f "$marker" ]]; then
+                # Read expected worktree path from marker file (first line)
+                EXPECTED_WORKTREE=$(head -1 "$marker" 2>/dev/null || true)
+                break
+            fi
+        done
+    fi
 
     if [[ -n "$EXPECTED_WORKTREE" ]]; then
-        # AC-1 (Issue #550): Check worktree directory exists before path validation
+        # AC-4 (Issue #31): Check worktree directory exists before path validation
         # Prevents Write tool from creating non-existent worktree directories
         if [[ ! -d "$EXPECTED_WORKTREE" ]]; then
             echo "HOOK_BLOCKED: Worktree does not exist: $EXPECTED_WORKTREE" | tee -a /tmp/claude-hook.log >&2
@@ -304,12 +359,23 @@ if [[ "$TOOL_NAME" == "Edit" || "$TOOL_NAME" == "Write" ]]; then
         fi
 
         if [[ -n "$FILE_PATH" ]]; then
+            # Resolve to absolute path for consistent comparison
+            REAL_FILE_PATH=$(realpath "$FILE_PATH" 2>/dev/null || echo "$FILE_PATH")
+            REAL_WORKTREE=$(realpath "$EXPECTED_WORKTREE" 2>/dev/null || echo "$EXPECTED_WORKTREE")
+
             # Check if file path is within the expected worktree
-            if ! echo "$FILE_PATH" | grep -qF "$EXPECTED_WORKTREE"; then
+            if [[ "$REAL_FILE_PATH" != "$REAL_WORKTREE"* ]]; then
                 echo "$(date +%H:%M:%S) WORKTREE_BLOCKED: Edit outside expected worktree" >> "$QUALITY_LOG"
                 echo "  Expected: $EXPECTED_WORKTREE" >> "$QUALITY_LOG"
                 echo "  Got: $FILE_PATH" >> "$QUALITY_LOG"
-                echo "HOOK_BLOCKED: Edit must be in worktree: $EXPECTED_WORKTREE (got: $FILE_PATH)" | tee -a /tmp/claude-hook.log >&2
+                {
+                    echo "HOOK_BLOCKED: File operation must be within worktree"
+                    echo "  Worktree: $EXPECTED_WORKTREE"
+                    echo "  File: $FILE_PATH"
+                    if [[ -n "${SEQUANT_ISSUE:-}" ]]; then
+                        echo "  Issue: #$SEQUANT_ISSUE"
+                    fi
+                } | tee -a /tmp/claude-hook.log >&2
                 exit 2
             fi
         fi
@@ -357,6 +423,31 @@ if [[ "${CLAUDE_HOOKS_FILE_LOCKING:-true}" == "true" ]]; then
     fi
 fi
 
+# === PRE-MERGE WORKTREE CLEANUP ===
+# Auto-remove worktree before `gh pr merge` to prevent --delete-branch failure
+# The worktree locks the branch, causing merge to partially fail
+if [[ "$TOOL_NAME" == "Bash" ]] && echo "$TOOL_INPUT" | grep -qE 'gh pr merge'; then
+    # Extract PR number from command
+    PR_NUM=$(echo "$TOOL_INPUT" | grep -oE 'gh pr merge [0-9]+' | grep -oE '[0-9]+')
+
+    if [[ -n "$PR_NUM" ]]; then
+        # Get the branch name for this PR
+        BRANCH_NAME=$(gh pr view "$PR_NUM" --json headRefName --jq '.headRefName' 2>/dev/null || true)
+
+        if [[ -n "$BRANCH_NAME" ]]; then
+            # Check if a worktree exists for this branch
+            # Note: worktree line is 2 lines before branch line in porcelain output
+            WORKTREE_PATH=$(git worktree list --porcelain 2>/dev/null | grep -B2 "branch refs/heads/$BRANCH_NAME" | grep "^worktree " | sed 's/^worktree //' || true)
+
+            if [[ -n "$WORKTREE_PATH" && -d "$WORKTREE_PATH" ]]; then
+                # Remove the worktree before merge proceeds
+                git worktree remove "$WORKTREE_PATH" --force 2>/dev/null || true
+                echo "PRE-MERGE: Removed worktree $WORKTREE_PATH for branch $BRANCH_NAME" >> /tmp/claude-hook.log
+            fi
+        fi
+    fi
+fi
+
 # === ALLOW EVERYTHING ELSE ===
 # Slash commands need: git, npm, file edits, gh pr/issue, MCP tools
 exit 0