resolve

<objective>

OSS maintainer fast-close workflow. PR number → three phases fire automatically:

1. PR intelligence — synthesize motivation from PR body, linked issues, thread; classify comments into action items
2. Conflict resolution — checkout PR branch (fork-aware), merge BASE_REF, resolve conflicts with contributor intent as priority lens
3. Action item implementation — implement each item as separate commit attributed to review comment, push to contributor's fork

Result: conflict-free PR branch pushed to fork, ready to merge — no GitHub UI.

Core invariant — transparent and reversible: every action = visible named git object. Use git merge (new commit, two parents), never git rebase (rewrites SHA, kills revert/cherry-pick). Each action item = own commit — granular revert always possible.

Bare comment text → skip to Codex dispatch (Step 12).

</objective>

<inputs>

• $ARGUMENTS: one of:
• Omitted → review-handoff mode: auto-detect PR from most recent .reports/review/*/review-report.md
• PR number (e.g. 42 or #42) or GitHub PR URL → pr mode
• report (bare word) → report mode: latest review findings as action items; no GitHub re-fetch
• 42 report or <URL> report → pr + report mode: aggregate live GitHub comments + review report, deduplicated in one pass
• Bare review comment text → comment dispatch mode (jumps to Step 12)
• --no-challenge: optional — skip challenge gate per item; all selected items treated as VALID
• --agent <name>: optional — use <name> agent for implementation instead of Codex; must be an implementation agent; bare name auto-prefixed with foundry: if no plugin prefix detected (e.g. --agent sw-engineer → foundry:sw-engineer; --agent linting-expert → foundry:linting-expert; --agent doc-scribe → foundry:doc-scribe); explicit prefix also accepted (--agent foundry:sw-engineer); see routing table in action-item-dispatch.md

</inputs>

<constants> CHALLENGE_TIMEOUT_S=300 # tightened from CLAUDE.md §6 default 900s CHALLENGE_POLL_S=90 # tightened from CLAUDE.md §6 default 300s

Bash timeout convention — # timeout: N annotations in bash blocks are honored by the Claude Code

Bash tool (sets tool-level timeout). Shell enforcement (timeout S cmd prefix) is NOT required for

skills executed exclusively via Claude Code. Shell prefix added only for commands that could hang

in direct-shell execution (git push, gh pr checkout).

</constants>

<workflow>

<!-- Symbol legend: ⚠ = warning/skipped (non-blocking, proceed with caution) · ⛔ = blocked/stop (halt workflow, do not proceed) -->

<!-- Agent resolution: see _OSS_SHARED/agent-resolution.md -->

Agent Resolution

# loads: oss-shared-resolver.md
_OSS_SHARED=$(python "${CLAUDE_PLUGIN_ROOT:-plugins/oss}/bin/resolve_shared_path.py" oss skills/_shared 2>/dev/null)  # timeout: 5000
_OSS_RESOLVE=$(ls -td ~/.claude/plugins/cache/borda-ai-rig/oss/*/skills/resolve 2>/dev/null | head -1)  # timeout: 5000
[ -z "$_OSS_RESOLVE" ] && _OSS_RESOLVE="plugins/oss/skills/resolve"

Read $_OSS_SHARED/oss-shared-resolver.md and execute its contents.

Read $_OSS_SHARED/agent-resolution.md. Contains: foundry check + fallback table. foundry not installed → use table to substitute each foundry:X with general-purpose. Agents this skill uses: foundry:sw-engineer, foundry:qa-specialist, foundry:linting-expert, foundry:doc-scribe, foundry:challenger.

<!-- Inline fallback (if agent-resolution.md unreadable): foundry:sw-engineer → general-purpose, foundry:qa-specialist → general-purpose, foundry:linting-expert → general-purpose, foundry:challenger → general-purpose. -->

Task hygiene: Before creating tasks, call TaskList. Per task:

• completed if done
• deleted if orphaned/irrelevant
• in_progress only if genuinely continuing

Step 1: Pre-flight

Extracted to bin/resolve_preflight.py — checks codex availability, gh binary + auth, syncs with remote. Caches positive results under .claude/state/preflight/ (4 h TTL). Emits CODEX_AVAILABLE=<bool> and GH_OK=true on stdout for eval; status messages go to stderr; exits non-zero only on hard failure (gh missing/unauthenticated, git pull conflict).

eval "$(python "${CLAUDE_PLUGIN_ROOT:-plugins/oss}/bin/resolve_preflight.py")"  # timeout: 30000

gh missing or not authenticated → script exits 1 (error printed above).

Codex missing: set CODEX_AVAILABLE=false — Steps 3–7 work without it. Step 8 degradation:

1. Simple, single-file items → foundry:sw-engineer
2. Complex/multi-file → skip with: ⚠ codex not found — skipping item #<id>. Install: /plugin marketplace add openai/codex-plugin-cc && /plugin install codex@openai-codex && /reload-plugins

Review-handoff auto-detect (when $ARGUMENTS is empty)

When $ARGUMENTS empty:

# Find most recent review output (written by /review to .reports/review/)
REVIEW_FILE=$(ls -t .reports/review/*/review-report.md 2>/dev/null | head -1)
if [ -z "$REVIEW_FILE" ]; then
    echo "No review output found in .reports/review/ — run /review <PR#> first, or provide a PR number"
    exit 1
fi
echo "→ Using: $REVIEW_FILE"

Read $REVIEW_FILE. Extract PR number from header:

• Pattern: ## Code Review: PR #<N> or ## Code Review: <N>
• Grep: grep -oE '(PR #|#)?[0-9]+' "$REVIEW_FILE" | head -1 | grep -oE '[0-9]+'

PR found → set $ARGUMENTS = <N>, proceed PR mode. Print: → Resolved PR #<N> from review output.

No PR number extractable → print: "Review output does not reference a PR — provide a PR number explicitly: /oss:resolve <PR#>" and exit 1.

Parse $ARGUMENTS:

[ -n "$CLAUDE_PLUGIN_ROOT" ] || { echo "Error: CLAUDE_PLUGIN_ROOT is unset — verify oss plugin installation and that skill is invoked via Claude Code plugin system"; exit 1; }  # timeout: 5000
[ -f "${CLAUDE_PLUGIN_ROOT}/bin/parse-resolve-args.py" ] || { echo "Error: parse-resolve-args.py not found — verify oss plugin installation"; exit 1; }  # timeout: 5000
# Defence-in-depth: capture parser output to a temp file and validate that every
# line is a plain VAR=value assignment (no shell metacharacters that could trigger
# command substitution, pipelines, or backgrounding) before sourcing. parse-resolve-args.py
# uses shlex.quote so its output is already safe, but validating here protects against
# future regressions or a tampered binary.
tmpenv=$(mktemp)  # timeout: 3000
trap 'rm -f "$tmpenv"' EXIT INT TERM
python "${CLAUDE_PLUGIN_ROOT}/bin/parse-resolve-args.py" "$ARGUMENTS" >"$tmpenv"  # timeout: 5000
if grep -qvE "^[A-Z_][A-Z0-9_]*=([A-Za-z0-9_./:#@+-]*|'[^']*')$" "$tmpenv"; then
    echo "Error: parse-resolve-args.py emitted unexpected output — refusing to source"
    cat "$tmpenv"
    exit 1
fi
. "$tmpenv"
# sets: PR_NUMBER, PR_URL, MODE, ARGUMENTS (leading '#' stripped only for comment-dispatch)

Unsupported flag check — after eval, scan remaining $ARGUMENTS for any --<token> not in {--no-challenge, --agent}. Found → invoke AskUserQuestion — (a) Abort (stop, re-invoke with correct flags) · (b) Continue ignoring (skip unknown tokens). Supported: --no-challenge, --agent <name>.

• MODE="pr+report" → strip report suffix conceptually (already captured separately); find latest review report via ls -t .reports/review/*/review-report.md 2>/dev/null | head -1; no report found → warn but continue in pr mode
• MODE="report" → find latest review report via ls -t .reports/review/*/review-report.md 2>/dev/null | head -1; no report found → stop with: "No review report found in .reports/review/ — run /review \<PR#> first, or provide a PR number"; extract PR# from header if present; no PR# in header → add branch safety check before Step 8 — `CURRENT=$(git branch --show-current); DEFAULT=$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's|refs/remotes/origin/||'); [ -z "$DEFAULT" ] && DEFAULT=$(git remote show origin 2>/dev/null |