diff --git a/.opencode/agents/bug-hunt-pool-supervisor.md b/.opencode/agents/bug-hunt-pool-supervisor.md index ef7e1e571..162b3f17e 100644 --- a/.opencode/agents/bug-hunt-pool-supervisor.md +++ b/.opencode/agents/bug-hunt-pool-supervisor.md @@ -228,334 +228,50 @@ Supervisor: Bug Detection Pool | Agent: bug-hunter" --repo-name "$repo" # ── IMMEDIATELY loop back ──────────────────────────────────── + ``` --- ## Worker Mode +In Worker Mode, this agent delegates to `bug-hunt-worker` for deep module +analysis. See `.opencode/agents/bug-hunt-worker.md` for the full worker +protocol including: clone isolation, analysis passes (error handling, +concurrency, security, boundary conditions, resource management, type +safety, spec alignment, code consistency, data flow), finding report +format, finding validation, severity criteria, and duplicate avoidance. + +**Quick reference** — Worker Mode steps: +1. Clone the repo to `/tmp//` (see Clone Isolation Protocol below). +2. Load the specification via `ref-reader`. +3. Check existing bug issues to avoid duplicates. +4. Run all nine analysis passes on the assigned module. +5. Validate each finding before filing (five-check gate). +6. File validated findings via `new-issue-creator`. +7. Clean up clone and exit. + ### Clone Isolation Protocol **CRITICAL: You MUST work in your own isolated clone. NEVER operate in /app.** -**HOSTNAME WARNING:** The Forgejo host is NOT necessarily -`git..com`. You MUST derive the git clone hostname from the -Forgejo base URL or PAT URL provided in your prompt — NOT from the -organization name. For example, if the Forgejo URL is -`https://git.cleverthis.com`, use `git.cleverthis.com` as the host, even -if the org is named `cleveragents`. +**HOSTNAME WARNING:** The Forgejo host is NOT necessarily `git..com`. +Derive the git clone hostname from the Forgejo base URL provided in your +prompt — NOT from the organization name. ```bash INSTANCE_ID="bug-hunter-$$-$(date +%s)" CLONE_DIR="/tmp/${INSTANCE_ID}" - -# Clone — use the host from FORGEJO_URL, NOT from the org name git clone https://@//.git "$CLONE_DIR" - -# Configure identity (read-only, but git needs this) cd "$CLONE_DIR" git config user.name "" git config user.email "" - -# All work happens INSIDE $CLONE_DIR — never reference /app ``` **CLEANUP on exit: `rm -rf "$CLONE_DIR"`** — always, even on error. -### Clone Failure Handling - -If `git clone` fails: - -1. **Check the hostname.** Verify you are using the host from the Forgejo - base URL (e.g., `git.cleverthis.com`), NOT a hostname derived from the - organization name (e.g., `git.cleveragents.com`). -2. **Retry once** with the corrected hostname if it was wrong. -3. **If still failing after retry, EXIT gracefully.** Report the clone - failure in your return value and move on. Do NOT file a Forgejo issue - about the clone failure — it is an agent environment problem, not a - product bug. -4. **NEVER file issues about TLS, DNS, or network failures** encountered - during your own clone operation. These are infrastructure issues in - your execution environment, not bugs in the product codebase. - -### Setup - -You receive: -- **Repo owner/name** — for Forgejo API calls -- **Instance ID** — unique identifier for this hunter instance -- **Forgejo PAT** — for HTTPS git auth and API access -- **Git full name / email** — for git identity -- **Forgejo username** — for API operations -- **Module focus** — specific module or package to analyze - -### Startup Sequence - -1. **Clone the repository** (per Clone Isolation Protocol above). - -2. **Load the specification** — invoke `ref-reader` with the clone - directory to get a structured summary of the project spec, rules, and - conventions. - -3. **Check existing bug issues** — query Forgejo for all open issues with - Type/Bug label. Build a knowledge base of known bugs to avoid duplicates. - -4. **Post coordination via tracking issue**: - local coordination_body="# 🕵️ Bug Hunter Worker Started - -**Instance ID**: $INSTANCE_ID -**Module Focus**: $module_focus -**Clone Directory**: $CLONE_DIR -**Timestamp**: $(date +'%Y-%m-%d %H:%M:%S') - -## Scanning Plan - -This worker instance will perform comprehensive bug detection analysis on the assigned module, focusing on: -- Error handling patterns -- Concurrency safety -- Security vulnerabilities -- Boundary condition handling -- Resource management issues - -## Coordination - -Other automation agents can track this worker's progress through this tracking issue and related bug reports. - ---- -**Automated by CleverAgents Bot** -Worker: Bug Detection | Agent: bug-hunter -**Worker Type**: Module Scanner" - - create_bug_hunter_announcement_issue "Worker $INSTANCE_ID Started" "Medium" "$coordination_body" - -### Analysis Process - -For the assigned module: - -1. **Read ALL source files** in the module: - ```bash - find "$CLONE_DIR/" -name "*.py" -type f - ``` - Read each file to load the full module into context. - -2. **Read the spec section** for this module: - Invoke `spec-reader` for the module's architectural context. - -3. **Run all analysis passes** on the module: - - ``` - module_findings = [] - module_findings += analyze_error_handling(module) - module_findings += analyze_concurrency(module) - module_findings += analyze_security(module) - module_findings += analyze_boundary_conditions(module) - module_findings += analyze_resource_management(module) - module_findings += analyze_type_safety(module) - module_findings += analyze_spec_alignment(module, spec_context) - module_findings += analyze_code_consistency(module) - module_findings += analyze_data_flow(module) - ``` - -4. **File issues for findings**: - ``` - for finding in module_findings: - # Dedup against known bugs - existing = search Forgejo for similar open issues - if duplicate found: - continue - - # MILESTONE SCOPE GUARD: Only critical/security bugs get the - # active milestone. Non-critical findings go to the backlog - # (no milestone + Priority/Backlog) to prevent scope explosion. - is_critical = (finding.severity in ("critical", "security") - or finding.blocks_milestone_acceptance) - invoke new-issue-creator with: - - Title: "BUG-HUNT: [] " - - Description: (see Finding Report Format below) - - Type: Bug - - Priority: Priority/Critical if is_critical else Priority/Backlog - - Milestone: current active milestone if is_critical else NONE - ``` - -5. **Exit** — Worker Mode completes after scanning the assigned module. - ---- - -## Analysis Passes - -### 1. Error Handling Analysis -- Bare `except:` or `except Exception:` that swallow errors silently -- Missing error handling on I/O operations -- Inconsistent error propagation -- Missing argument validation -- Catch-and-ignore patterns - -### 2. Concurrency Analysis -- Shared mutable state without locks -- Race conditions in read-modify-write sequences -- Deadlock potential, missing timeouts -- Async operations without proper await or error handling - -### 3. Security Analysis -- SQL injection, command injection, path traversal -- Hardcoded secrets -- Missing auth/authz checks -- Insecure deserialization - -### 4. Boundary Condition Analysis -- Off-by-one errors -- Empty collection handling, None handling -- Integer overflow potential, Unicode handling -- Large input handling - -### 5. Resource Management Analysis -- Unclosed files (open without context manager) -- Unclosed connections, memory leaks -- Temporary file cleanup, process cleanup - -### 6. Type Safety Analysis -- Type annotation gaps -- Incorrect type narrowing, unsafe casts -- Protocol violations, generic type misuse - -### 7. Specification Alignment Analysis -- Missing features, wrong behavior -- Missing constraints, API mismatches - -### 8. Code Consistency Analysis -- Inconsistent naming, duplicate logic -- Dead code, inconsistent return types - -### 9. Data Flow Analysis -- Tainted data propagation -- Missing sanitization at trust boundaries -- Data type mismatches - ---- - -## Finding Report Format - -Each bug issue body should follow this format: - -```markdown -## Bug Report: [Category] — [Brief Description] - -### Severity Assessment -- **Impact**: -- **Likelihood**: -- **Priority**: - -### Location -- **File**: `` -- **Function/Class**: `` -- **Lines**: - -### Description - - -### Evidence -(Relevant code snippet showing the issue) - -### Expected Behavior - - -### Actual Behavior - - -### Suggested Fix - - -### Category - - -### TDD Note -After this bug issue is verified, a corresponding Type/Testing issue will be -created for TDD. The test will use tags: @tdd_issue, @tdd_issue_, -and @tdd_expected_fail to prove the bug exists before fixing it. -``` - ---- - -## TDD Workflow Awareness - -When filing Type/Bug issues: -- The project follows Test-Driven Development for bug fixes -- A separate Type/Testing issue will be created with TDD tests -- These tests will have special tags that invert their behavior -- The bug fix PR must remove the @tdd_expected_fail tag -- This ensures bugs are properly tested before being fixed - -Your job is to find and report bugs. The TDD workflow happens after your report. - ---- - -## Severity Assessment Criteria - -| Severity | Criteria | -|---|---| -| **Critical** | Data loss, security vulnerability, crash in common paths | -| **High** | Incorrect behavior in normal usage, resource leaks under load | -| **Medium** | Edge case failures, inconsistencies, minor spec deviations | -| **Low** | Code quality issues, potential future bugs, cosmetic inconsistencies | - ---- - -## Duplicate Avoidance - -Before filing any finding: - -1. **Search Forgejo** for open issues with similar descriptions. -2. **Check BUG-HUNT issues** — search for "BUG-HUNT:" title prefix. -3. **Check UAT issues** — the UAT tester may have already found the same bug. -4. **Check the findings log** from other bug-hunter instances (via session - state comments). -5. If uncertain, **file the issue** but note the potential overlap. - ---- - -## Bot Signature (Required on ALL Forgejo Content) - -Every comment, issue body, PR description, and review you post to Forgejo -MUST end with this signature block: - -``` ---- -**Automated by CleverAgents Bot** -Supervisor: Bug Hunting | Agent: bug-hunter -``` - -Append this to the END of every piece of content you create on Forgejo. -No exceptions — every comment, every issue body, every PR description. - -## Finding Validation (Required Before Filing) - -Before filing ANY issue, you MUST validate the finding: - -1. **Verify you have actual code evidence.** Every finding MUST include a - real code snippet copied from the repository. If you cannot read the - actual source file, do NOT file the issue. Speculative findings based - on assumptions about what the code "might" do are NOT acceptable. - -2. **Verify environment assumptions.** Do NOT file issues about - infrastructure problems (DNS, TLS, network) that you encountered during - your own setup. These are agent environment issues, not product bugs. - Specifically: if `git clone` fails, that is YOUR problem, not a product - bug. - -3. **Verify the finding is actionable.** Each finding must identify a - specific file, function, and line range with a concrete bug. Vague - findings like "review concurrency in this module" or "review error - handling in this directory" are NOT bugs — they are audit requests. - Do NOT file them. - -4. **Verify against the actual codebase, not hypotheticals.** You must - READ the code and confirm the bug exists. Do not file issues based on - what you think the code might look like. If you cannot access the code, - skip the module and report it as inaccessible in your return value. - -5. **Severity must match evidence.** Do not mark findings as "Critical" - unless you can demonstrate data loss, security vulnerability, or crash - in a common code path with specific evidence. +If `git clone` fails: check the hostname, retry once, then EXIT gracefully. +Do NOT file issues about TLS, DNS, or network failures in your environment. --- @@ -568,25 +284,22 @@ Before filing ANY issue, you MUST validate the finding: - **Be specific.** Every finding must include file paths, function names, code snippets, and clear explanations. - **Prioritize real bugs over style issues.** Don't file issues for things - that linters or type checkers should catch. + that linters or Type checkers should catch. - **Read the spec before flagging deviations.** A deviation is only a bug if the spec explicitly requires different behavior. - **Use your large context window.** Read entire modules at once to detect cross-function and cross-file issues. - **In Worker Mode, exit promptly.** Scan the assigned module and exit so the pool supervisor can dispatch new work. -- **NEVER file speculative or unverified findings.** See "Finding Validation" - section above. Every issue you file must have concrete code evidence. +- **NEVER file speculative or nunverified findings.** Every issue you file + must have concrete code evidence (see `bug-hunt-worker.md`). - **Route non-critical findings to the backlog.** Only critical bugs and security vulnerabilities that block the milestone's core acceptance criteria get assigned to the active milestone. All other findings are created with - no milestone and `Priority/Backlog`. This prevents scope explosion in - active milestones. + no milestone and `Priority/Backlog`. - **NEVER file issues about your own infrastructure.** TLS/SSL failures, - DNS resolution errors, clone failures, tool crashes, and network issues - in YOUR execution environment are NOT product bugs. They are agent - environment problems. If you cannot clone or access the code, exit - gracefully — do not file a bug report about it. + DNS resolution errors, clone failures, and network issues in YOUR execution + environment are NOT product bugs. ---