fix(next-task): task-discoverer skips issues with open PRs (#236) (#243)

* fix(next-task): task-discoverer skips issues with open PRs (#236)

Add Phase 2.5 to the discover-tasks skill that fetches open PRs via
`gh pr list` and builds a Set of linked issue numbers. Issues are
matched by three patterns: branch name suffix (-NNN), PR body closing
keywords (closes/fixes/resolves #N), and PR title (#N) convention.

Matched issues are excluded in Phase 3 with an [INFO] log message.
Non-GitHub sources skip this phase entirely (empty Set).

Updated task-discoverer agent role list, CHANGELOG, and regenerated
OpenCode adapters.

Fixes #236

* fix(next-task): harden PR-exclusion logic in discover-tasks skill

- Add default prLinkedIssues = new Set() before GitHub-only block (fixes
  ReferenceError for non-GitHub sources)
- Wrap JSON.parse in try/catch with [WARN] fallback
- Add null guards on pr.headRefName and pr.title
- Expand closing-keyword regex to cover GitHub's full keyword set
  (close, closed, closes, fix, fixed, fixes, resolve, resolved, resolves)
  with word-boundary anchor to prevent false positives
- Switch title pattern to matchAll() to capture multiple (#N) references
- Add filterByPriority(filtered, ...) call to wire variable pipeline
- Replace em dashes with plain ASCII hyphens per project style guide
- Document 100-PR limit in bash comment
- Update agent Execution bullets to list PR-exclusion logic

* docs: add PR-exclusion step to task-discoverer reference

* enhance(next-task): apply /enhance findings to task-discoverer agent and skill

Agent (task-discoverer.md):
- Fix frontmatter description: remove behavioral instruction, describe invocation context
- Add role identity sentence ("You discover, filter, score...")
- Add Output Format section (mirrors skill output)
- Add Error Handling section
- Move Constraints to end of file (after Integration Points)
- Add "Exclude issues with open PRs" to Constraints
- Strengthen "Do not" to "NEVER bypass the skill"

Skill (discover-tasks/SKILL.md):
- Add allowed-tools to frontmatter for explicit tool permissions
- Expand trigger phrases (add "what should I work on", "list open issues")
- Add "When to Use" section
- Fix stale directory reference in Phase 1 comment
- Add conditional guard to Phase 6 for non-GitHub sources
- Add PR pagination limit to Constraints section

* fix: address PR review comments (Codex + Gemini)

- Add note about branch-suffix heuristic false positives (release-2026 pattern)
- Fix task.score not assigned before sort - use map+score then sort
- Fix Phase 6 source guard: remove undefined $SOURCE var, use clear prose note
  with policy.taskSource reference instead of broken shell conditional

* fix: address Copilot review feedback

- Add Bash(grep:*) to allowed-tools (local tasks.md phase uses grep via bash)
- Add const fs = require('fs') to Phase 2.5 JS block (was missing import)
- Add explicit policy.taskSource comment to Phase 2.5 bash block
  to clarify GitHub-only condition (replaces ambiguous prose-only guard)

Author: avifenesh

CHANGELOG.md

@@ -11,6 +11,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- **task-discoverer**: Exclude issues that already have an open PR from discovery results (GitHub source only). Detection uses branch name suffix, PR body closing keywords (`closes/fixes/resolves #N`), and PR title `(#N)` convention. Fixes #236.
+
 - **`/debate` 240s timeout enforcement** — All tool invocations in the debate workflow now enforce a hard 240-second timeout. Round 1 proposer timeouts abort the debate; round 1 challenger timeouts proceed with an uncontested position; round 2+ timeouts synthesize from completed rounds. Added "all rounds timeout" error path (`[ERROR] Debate failed: all tool invocations timed out.`). Timeout handling is consistent across the Claude Code command, OpenCode adapter, Codex adapter, and the `debate-orchestrator` agent. Restored missing "Round 2+: Challenger Follow-up" template in the OpenCode adapter SKILL.md. Fixes issue #233.
 
 - **`/next-task` review loop exit conditions** — The Phase 9 review loop now continues iterating until all issues are resolved or a stall is detected (MAX_STALLS reduced from 2 to 1: two consecutive identical-hash iterations = stall). The `orchestrate-review` skill now uses `completePhase()` instead of `updateFlow()` to properly advance workflow state. Added `pre-review-gates` and `docs-update` to the `PHASES` array and `RESULT_FIELD_MAP` in `workflow-state.js`, ensuring these phases can be tracked and resumed correctly. Fixes issue #235.

adapters/opencode/agents/task-discoverer.md

@@ -1,6 +1,6 @@
 ---
 name: task-discoverer
-description: Discover and prioritize tasks from configured sources. CRITICAL - You MUST use AskUserQuestion tool to present task selection as checkboxes.
+description: "Discover and prioritize tasks from configured sources. Use after policy selection in /next-task workflow to fetch, filter, score, and present issues for user selection via checkbox UI."
 mode: subagent
 ---
 
@@ -12,13 +12,16 @@ mode: subagent
 
 # Task Discoverer Agent
 
+You discover, filter, score, and present tasks from configured sources for user selection.
+
 **CRITICAL**: You MUST use the AskUserQuestion tool to present task selection as checkboxes. Do NOT present tasks as plain text or ask users to type a number.
 
 ## Execution
 
 You MUST execute the `discover-tasks` skill to perform task discovery. The skill contains:
 - Source fetching patterns (GitHub, GitLab, local, custom)
 - Claimed task exclusion logic
+- PR-linked issue exclusion logic (GitHub only)
 - Priority filtering
 - Scoring algorithm
 - AskUserQuestion patterns with 30-char label limit
@@ -35,11 +38,12 @@ Reads from workflow state (`flow.json`):
 2. Load policy from workflow state
 3. Fetch tasks from configured source
 4. Exclude tasks already claimed by other workflows
-5. Filter by priority policy
-6. Score and rank top 5 tasks
-7. Present via AskUserQuestion with checkbox UI
-8. Update state with selected task
-9. Post comment to issue (GitHub only)
+5. Exclude issues with open PRs (GitHub only) - single `gh pr list` call
+6. Filter by priority policy
+7. Score and rank top 5 tasks
+8. Present via AskUserQuestion with checkbox UI
+9. Update state with selected task
+10. Post comment to issue (GitHub only)
 
 ## [WARN] OpenCode Label Limit
 
@@ -57,14 +61,6 @@ All AskUserQuestion option labels MUST be max 30 characters. Use the truncation
 | custom | Use cached CLI/MCP/Skill capabilities |
 | other | Interpret user description |
 
-## Constraints
-
-- Do not bypass the skill - it contains the authoritative patterns
-- MUST use AskUserQuestion for selection (structured UI)
-- Exclude tasks in `tasks.json` registry (claimed by other workflows)
-- Max 5 tasks presented to user
-- Labels max 30 characters
-
 ## Quality Multiplier
 
 Uses **sonnet** model because:
@@ -77,3 +73,30 @@ Uses **sonnet** model because:
 This agent is invoked by:
 - Phase 2 of `/next-task` workflow
 - After policy selection, before worktree setup
+
+## Output Format
+
+```markdown
+## Task Selected
+
+**Task**: #{id} - {title}
+**Source**: {source}
+**URL**: {url}
+
+Proceeding to worktree setup...
+```
+
+## Error Handling
+
+- No tasks found: Suggest creating issues, running /audit-project, or using 'all' priority filter
+- gh/glab CLI not available: Report error with install instructions, do not attempt workaround
+- flow.json missing or corrupt: Report state error, suggest restarting /next-task workflow
+
+## Constraints
+
+- NEVER bypass the skill - it contains the authoritative patterns
+- MUST use AskUserQuestion for selection (structured UI)
+- Exclude tasks in `tasks.json` registry (claimed by other workflows)
+- Exclude issues with open PRs (GitHub source only)
+- Max 5 tasks presented to user
+- Labels max 30 characters

adapters/opencode/skills/debate/SKILL.md

@@ -261,7 +261,7 @@ Platform state directory:
 
 ## External Tool Quick Reference
 
-> Canonical source: consult skill (`consult/SKILL.md`). This table is for **planning reference only** -- always invoke via `Skill: consult`, which handles safe question passing, temp file creation, and cleanup. Do NOT execute these commands directly.
+> Canonical source: `plugins/consult/skills/consult/SKILL.md`. This table is for **planning reference only** -- always invoke via `Skill: consult`, which handles safe question passing, temp file creation, and cleanup. Do NOT execute these commands directly.
 
 ### Safe Command Patterns
 

adapters/opencode/skills/discover-tasks/SKILL.md

@@ -1,13 +1,18 @@
 ---
 name: discover-tasks
-description: "Use when user asks to \"discover tasks\", \"find next task\", or \"prioritize issues\". Discovers and ranks tasks from GitHub, GitLab, local files, and custom sources."
-version: 5.1.0
+description: "Use when user asks to \"discover tasks\", \"find next task\", \"prioritize issues\", \"what should I work on\", or \"list open issues\". Discovers and ranks tasks from GitHub, GitLab, local files, and custom sources."
+version: 5.1.1
+allowed-tools: "Bash(gh:*), Bash(glab:*), Bash(git:*), Bash(grep:*), Grep, Read, AskUserQuestion"
 ---
 
 # discover-tasks
 
 Discover tasks from configured sources, validate them, and present for user selection.
 
+## When to Use
+
+Invoked during Phase 2 of `/next-task` workflow, after policy selection. Also usable standalone when the user wants to discover and select tasks from configured sources.
+
 ## Workflow
 
 ### Phase 1: Load Policy and Claimed Tasks
@@ -46,12 +51,29 @@ done
 **Custom Source:**
 *(JavaScript reference - not executable in OpenCode)*
 
+### Phase 2.5: Collect PR-Linked Issues (GitHub only)
+
+*(JavaScript reference - not executable in OpenCode)*
+
+For GitHub sources (`policy.taskSource === 'github'` or `'gh-issues'`), fetch all open PRs and build a Set of issue numbers that already have an associated PR. Skip to Phase 3 for all other sources.
+
+```bash
+# Only run when policy.taskSource is 'github' or 'gh-issues'
+# Note: covers up to 100 open PRs. If repo has more, some linked issues may not be excluded.
+gh pr list --state open --json number,title,body,headRefName --limit 100 > /tmp/gh-prs.json
+```
+
+*(JavaScript reference - not executable in OpenCode)*
+
 ### Phase 3: Filter and Score
 
 **Exclude claimed tasks:**
 *(JavaScript reference - not executable in OpenCode)*
 
-**Apply priority filter:**
+**Exclude issues with open PRs (GitHub only):**
+*(JavaScript reference - not executable in OpenCode)*
+
+**Apply priority filter** (pass `filtered` through scoring pipeline):
 *(JavaScript reference - not executable in OpenCode)*
 
 **Score tasks:**
@@ -71,7 +93,10 @@ done
 
 ### Phase 6: Post Comment (GitHub only)
 
+**Skip this phase entirely for non-GitHub sources (GitLab, local, custom).**
+
 ```bash
+# Only run for GitHub source. Use policy.taskSource from Phase 1 to check.
 gh issue comment "$TASK_ID" --body "[BOT] Workflow started for this issue."
 ```
 
@@ -99,4 +124,6 @@ If no tasks found:
 - MUST use AskUserQuestion for task selection (not plain text)
 - Labels MUST be max 30 characters
 - Exclude tasks already claimed by other workflows
+- Exclude issues that already have an open PR (GitHub source only)
+- PR-link detection covers up to 100 open PRs (--limit 100 is the fetch cap)
 - Top 5 tasks only

docs/reference/AGENTS.md

@@ -60,8 +60,8 @@ AgentSys uses 41 specialized agents across 12 plugins (11 have agents - ship use
 **What it does:**
 1. Loads claimed tasks from `tasks.json` (excludes them)
 2. Fetches from GitHub/GitLab/local files/custom CLI
-3. Applies priority scoring (labels, blockers, age, reactions)
-4. Validates tasks against codebase
+3. Excludes issues that already have an open PR (GitHub source only)
+4. Applies priority scoring (labels, blockers, age, reactions)
 5. Presents top 5 via AskUserQuestion checkboxes
 6. Posts "Workflow Started" comment to GitHub issue
 

plugins/next-task/agents/task-discoverer.md

@@ -1,6 +1,6 @@
 ---
 name: task-discoverer
-description: Discover and prioritize tasks from configured sources. CRITICAL - You MUST use AskUserQuestion tool to present task selection as checkboxes.
+description: "Discover and prioritize tasks from configured sources. Use after policy selection in /next-task workflow to fetch, filter, score, and present issues for user selection via checkbox UI."
 tools:
   - Skill
   - Bash(gh:*)
@@ -14,13 +14,16 @@ model: sonnet
 
 # Task Discoverer Agent
 
+You discover, filter, score, and present tasks from configured sources for user selection.
+
 **CRITICAL**: You MUST use the AskUserQuestion tool to present task selection as checkboxes. Do NOT present tasks as plain text or ask users to type a number.
 
 ## Execution
 
 You MUST execute the `discover-tasks` skill to perform task discovery. The skill contains:
 - Source fetching patterns (GitHub, GitLab, local, custom)
 - Claimed task exclusion logic
+- PR-linked issue exclusion logic (GitHub only)
 - Priority filtering
 - Scoring algorithm
 - AskUserQuestion patterns with 30-char label limit
@@ -37,11 +40,12 @@ Reads from workflow state (`flow.json`):
 2. Load policy from workflow state
 3. Fetch tasks from configured source
 4. Exclude tasks already claimed by other workflows
-5. Filter by priority policy
-6. Score and rank top 5 tasks
-7. Present via AskUserQuestion with checkbox UI
-8. Update state with selected task
-9. Post comment to issue (GitHub only)
+5. Exclude issues with open PRs (GitHub only) - single `gh pr list` call
+6. Filter by priority policy
+7. Score and rank top 5 tasks
+8. Present via AskUserQuestion with checkbox UI
+9. Update state with selected task
+10. Post comment to issue (GitHub only)
 
 ## [WARN] OpenCode Label Limit
 
@@ -67,14 +71,6 @@ function truncateLabel(num, title) {
 | custom | Use cached CLI/MCP/Skill capabilities |
 | other | Interpret user description |
 
-## Constraints
-
-- Do not bypass the skill - it contains the authoritative patterns
-- MUST use AskUserQuestion for selection (structured UI)
-- Exclude tasks in `tasks.json` registry (claimed by other workflows)
-- Max 5 tasks presented to user
-- Labels max 30 characters
-
 ## Quality Multiplier
 
 Uses **sonnet** model because:
@@ -87,3 +83,30 @@ Uses **sonnet** model because:
 This agent is invoked by:
 - Phase 2 of `/next-task` workflow
 - After policy selection, before worktree setup
+
+## Output Format
+
+```markdown
+## Task Selected
+
+**Task**: #{id} - {title}
+**Source**: {source}
+**URL**: {url}
+
+Proceeding to worktree setup...
+```
+
+## Error Handling
+
+- No tasks found: Suggest creating issues, running /audit-project, or using 'all' priority filter
+- gh/glab CLI not available: Report error with install instructions, do not attempt workaround
+- flow.json missing or corrupt: Report state error, suggest restarting /next-task workflow
+
+## Constraints
+
+- NEVER bypass the skill - it contains the authoritative patterns
+- MUST use AskUserQuestion for selection (structured UI)
+- Exclude tasks in `tasks.json` registry (claimed by other workflows)
+- Exclude issues with open PRs (GitHub source only)
+- Max 5 tasks presented to user
+- Labels max 30 characters