github-issue-resolver

# GitHub Issue Resolver

Autonomous agent for discovering, analyzing, and fixing open GitHub issues — with a 5-layer guardrail system.

## ⚠️ GUARDRAILS — Read First

**Every action goes through guardrails.** Before any operation:

1. Load `guardrails.json` config
2. Validate scope (repo, branch, path)
3. Check action gate (auto/notify/approve)
4. Validate command against allowlist
5. Log to audit trail

For guardrail details, see [references/guardrails-guide.md](references/guardrails-guide.md).

### Key Rules (Non-Negotiable)
- **Never touch protected branches** (main, master, production)
- **Never modify** .env, secrets, CI configs, credentials
- **Never force push**
- **Never modify dependency files** without explicit approval
- **Never modify own skill/plugin files**
- **One issue at a time** — finish or abandon before starting new
- **All dangerous actions require user approval** (write code, commit, push, PR)
- **Everything is logged** to `audit/` directory

---

## Workflow

### Phase 1 — Issue Discovery

**Trigger:** User provides a GitHub repository (`owner/repo`).

**Steps:**

1. **Validate repo** against guardrails:
   ```bash
   python3 scripts/guardrails.py repo <owner> <repo>
   ```
   If blocked, tell the user and stop.

2. **Fetch, score, and present issues** using the recommendation engine:
   ```bash
   python3 scripts/recommend.py <owner> <repo>
   ```
   This automatically fetches open issues, filters out PRs, scores them by severity/impact/effort/freshness, and presents a formatted recommendation.

   **Always use `recommend.py`** — never manually format issue output. The script ensures consistent presentation every time.

   For raw JSON (e.g., for further processing):
   ```bash
   python3 scripts/recommend.py <owner> <repo> --json
   ```

**⏹️ STOP. Wait for user to select an issue.**

---

### Phase 2 — Fixing

**Trigger:** User selects an issue.

**Steps:**

1. **Lock the issue** (one-at-a-time enforcement):
   ```bash
   python3 scripts/gu...