panopticon-cli 0.4.32 → 0.5.0

package/scripts/tldr-post-edit

@@ -0,0 +1,72 @@
+#!/bin/bash
+# ~/.panopticon/bin/tldr-post-edit
+# PostToolUse hook on Edit/Write — notifies TLDR to re-warm after code changes.
+#
+# Tracks dirty files in a lightweight file. When the dirty count exceeds a
+# threshold, triggers a background re-warm so the index stays fresh.
+
+# Don't use set -e — never break Claude Code execution
+INPUT=$(cat 2>/dev/null || echo '{}')
+
+# Only act on Edit and Write tools
+TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // ""' 2>/dev/null)
+if [ "$TOOL_NAME" != "Edit" ] && [ "$TOOL_NAME" != "Write" ]; then
+  exit 0
+fi
+
+# Extract file path
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // ""' 2>/dev/null)
+if [ -z "$FILE_PATH" ]; then
+  exit 0
+fi
+
+# Only track code files
+EXT="${FILE_PATH##*.}"
+EXT_LOWER=$(echo "$EXT" | tr '[:upper:]' '[:lower:]')
+case "$EXT_LOWER" in
+  ts|tsx|js|jsx|py|java|go|rs|cpp|c|h|hpp|rb|php|kt|swift|cs|scala|lua|ex|exs)
+    ;;
+  *)
+    exit 0
+    ;;
+esac
+
+# Find project root (where .venv lives)
+PROJECT_DIR=""
+DIR="$(dirname "$FILE_PATH")"
+while [ "$DIR" != "/" ]; do
+  if [ -d "$DIR/.venv" ]; then
+    PROJECT_DIR="$DIR"
+    break
+  fi
+  DIR=$(dirname "$DIR")
+done
+
+if [ -z "$PROJECT_DIR" ]; then
+  exit 0
+fi
+
+# Track dirty files
+DIRTY_FILE="$PROJECT_DIR/.tldr/dirty-files"
+mkdir -p "$PROJECT_DIR/.tldr" 2>/dev/null || true
+
+# Append the changed file (deduplicated on warm)
+REL_PATH="${FILE_PATH#$PROJECT_DIR/}"
+echo "$REL_PATH" >> "$DIRTY_FILE" 2>/dev/null || true
+
+# Count dirty files (fast line count)
+DIRTY_COUNT=$(wc -l < "$DIRTY_FILE" 2>/dev/null || echo 0)
+
+# Trigger background re-warm after 10 edits (keeps index reasonably fresh)
+WARM_THRESHOLD=10
+if [ "$DIRTY_COUNT" -ge "$WARM_THRESHOLD" ]; then
+  TLDR_BIN="$PROJECT_DIR/.venv/bin/tldr"
+  if [ -x "$TLDR_BIN" ]; then
+    # Clear dirty tracking before warm
+    : > "$DIRTY_FILE" 2>/dev/null || true
+    # Background warm — non-blocking
+    (cd "$PROJECT_DIR" && "$TLDR_BIN" warm . --background) >/dev/null 2>&1 &
+  fi
+fi
+
+exit 0

package/scripts/tldr-read-enforcer

@@ -0,0 +1,275 @@
+#!/bin/bash
+# ~/.panopticon/bin/tldr-read-enforcer
+# PreToolUse hook on Read — intercepts file reads and returns TLDR summaries
+# for large code files, saving 90-95% of context tokens.
+#
+# Bypasses (allows normal read):
+#   - Files < 3KB (small enough to read directly)
+#   - Reads with offset/limit (targeted reads for editing)
+#   - Non-code files (configs, docs, json, etc.)
+#   - No .venv available (TLDR not installed)
+#   - TLDR command fails (graceful degradation)
+#   - Summary too sparse to be useful (< 100 tokens for file > 5KB)
+#   - Recently edited files (in .tldr/dirty-files — agent needs to verify changes)
+
+# Don't use set -e — never break Claude Code execution
+INPUT=$(cat 2>/dev/null || echo '{}')
+
+# Only act on Read tool
+TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // ""' 2>/dev/null)
+if [ "$TOOL_NAME" != "Read" ]; then
+  exit 0
+fi
+
+# Extract Read parameters
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // ""' 2>/dev/null)
+OFFSET=$(echo "$INPUT" | jq -r '.tool_input.offset // empty' 2>/dev/null)
+LIMIT=$(echo "$INPUT" | jq -r '.tool_input.limit // empty' 2>/dev/null)
+
+# Bypass: targeted reads (offset or limit specified — agent is reading for editing)
+if [ -n "$OFFSET" ] || [ -n "$LIMIT" ]; then
+  exit 0
+fi
+
+# Bypass: file doesn't exist
+if [ ! -f "$FILE_PATH" ]; then
+  exit 0
+fi
+
+# Bypass: small files (< 3KB)
+FILE_SIZE=$(stat -c%s "$FILE_PATH" 2>/dev/null || echo 0)
+if [ "$FILE_SIZE" -lt 3072 ]; then
+  exit 0
+fi
+
+# Bypass: non-code files
+EXT="${FILE_PATH##*.}"
+EXT_LOWER=$(echo "$EXT" | tr '[:upper:]' '[:lower:]')
+case "$EXT_LOWER" in
+  ts|tsx|js|jsx|py|java|go|rs|cpp|c|h|hpp|rb|php|kt|swift|cs|scala|lua|ex|exs)
+    # Code file — continue to TLDR
+    ;;
+  *)
+    # Non-code — allow normal read
+    exit 0
+    ;;
+esac
+
+# Find the .venv/bin/tldr binary
+# Check workspace first, then project root
+TLDR_BIN=""
+DIR="$(dirname "$FILE_PATH")"
+while [ "$DIR" != "/" ]; do
+  if [ -x "$DIR/.venv/bin/tldr" ]; then
+    TLDR_BIN="$DIR/.venv/bin/tldr"
+    PROJECT_DIR="$DIR"
+    break
+  fi
+  DIR=$(dirname "$DIR")
+done
+
+# Bypass: no TLDR binary found
+if [ -z "$TLDR_BIN" ]; then
+  exit 0
+fi
+
+# Get relative path from project root
+REL_PATH="${FILE_PATH#$PROJECT_DIR/}"
+
+# Bypass: recently edited files (agent needs to verify its own changes)
+# The post-edit hook tracks edits in .tldr/dirty-files
+DIRTY_FILE="$PROJECT_DIR/.tldr/dirty-files"
+if [ -f "$DIRTY_FILE" ] && grep -qxF "$REL_PATH" "$DIRTY_FILE" 2>/dev/null; then
+  exit 0
+fi
+
+# Detect language from extension for tldr --lang flag
+case "$EXT_LOWER" in
+  ts|tsx)      TLDR_LANG="typescript" ;;
+  js|jsx)      TLDR_LANG="javascript" ;;
+  py)          TLDR_LANG="python" ;;
+  go)          TLDR_LANG="go" ;;
+  rs)          TLDR_LANG="rust" ;;
+  java|kt)     TLDR_LANG="java" ;;
+  rb)          TLDR_LANG="ruby" ;;
+  *)           TLDR_LANG="python" ;;
+esac
+
+# Strip file extension — tldr context expects module paths without extension
+# e.g., "src/lib/agents" not "src/lib/agents.ts"
+MODULE_PATH="${REL_PATH%.*}"
+
+# Try to get TLDR context for this file (module path mode)
+TLDR_OUTPUT=$("$TLDR_BIN" context "$MODULE_PATH" --lang "$TLDR_LANG" 2>/dev/null)
+TLDR_EXIT=$?
+
+# Quality gate: check if context output is too sparse to be useful.
+# Pattern: "~XX tokens" where XX < 100 means the summary captured almost nothing.
+# This happens with test files (describe/it blocks) and type-only files.
+CONTEXT_SPARSE=false
+if [ $TLDR_EXIT -eq 0 ] && [ -n "$TLDR_OUTPUT" ]; then
+  CTX_TOKENS=$(echo "$TLDR_OUTPUT" | grep -oP '\~\K\d+(?= tokens)' || echo "0")
+  if [ "$CTX_TOKENS" -lt 100 ] && [ "$FILE_SIZE" -gt 5120 ]; then
+    CONTEXT_SPARSE=true
+  fi
+fi
+
+# Fallback: if context failed, was sparse, or empty — try extract command
+# extract works on actual file paths (including .tsx) and returns structured JSON
+if [ $TLDR_EXIT -ne 0 ] || [ -z "$TLDR_OUTPUT" ] || [ "$CONTEXT_SPARSE" = true ]; then
+  EXTRACT_JSON=$("$TLDR_BIN" extract "$REL_PATH" 2>/dev/null)
+  EXTRACT_EXIT=$?
+  if [ $EXTRACT_EXIT -eq 0 ] && [ -n "$EXTRACT_JSON" ]; then
+    # Check if extract found any real content
+    EXTRACT_COUNTS=$(echo "$EXTRACT_JSON" | python3 -c "
+import json, sys
+try:
+    d = json.load(sys.stdin)
+    nf = len(d.get('functions', []))
+    nc = len(d.get('classes', []))
+    print(f'{nf} {nc}')
+except:
+    print('0 0')
+" 2>/dev/null)
+    EXTRACT_FUNCS=$(echo "$EXTRACT_COUNTS" | cut -d' ' -f1)
+    EXTRACT_CLASSES=$(echo "$EXTRACT_COUNTS" | cut -d' ' -f2)
+
+    # If extract also found nothing useful, bypass entirely
+    if [ "${EXTRACT_FUNCS:-0}" -eq 0 ] && [ "${EXTRACT_CLASSES:-0}" -eq 0 ]; then
+      # Neither context nor extract found useful content — let the agent read the file
+      exit 0
+    fi
+
+    # Convert extract JSON to a readable summary with language-appropriate syntax
+    TLDR_OUTPUT=$(echo "$EXTRACT_JSON" | python3 -c "
+import json, sys
+try:
+    data = json.load(sys.stdin)
+    lang = '$TLDR_LANG'
+    lines = []
+    fname = data.get('file_path', '$REL_PATH')
+    short = fname.split('/')[-1]
+    lines.append(f'## Code Context: {fname}')
+    lines.append('')
+
+    # Language-appropriate function keyword
+    fn_kw = {'typescript': 'function', 'javascript': 'function', 'python': 'def',
+             'go': 'func', 'rust': 'fn', 'java': '', 'ruby': 'def'}.get(lang, 'function')
+
+    for func in data.get('functions', []):
+        name = func.get('name', '?')
+        params = ', '.join(
+            p.get('name','') + (': ' + p.get('type','') if p.get('type') else '')
+            for p in func.get('parameters', [])
+        )
+        ret = func.get('return_type', '')
+        doc = (func.get('docstring') or '')[:80]
+        line = func.get('start_line') or '?'
+        sig = f'{fn_kw} {name}({params})'.strip()
+        if ret:
+            if lang in ('typescript', 'javascript', 'go', 'rust'):
+                sig += f': {ret}'
+            else:
+                sig += f' -> {ret}'
+        lines.append(f'{name} ({short}:{line})')
+        lines.append(f'   {sig}')
+        if doc:
+            lines.append(f'   // {doc}')
+        lines.append('')
+
+    for cls in data.get('classes', []):
+        name = cls.get('name', '?')
+        line = cls.get('start_line') or '?'
+        lines.append(f'class {name} ({short}:{line})')
+        for m in cls.get('methods', []):
+            mname = m.get('name', '?')
+            lines.append(f'   .{mname}()')
+        lines.append('')
+
+    nfunc = len(data.get('functions', []))
+    ncls = len(data.get('classes', []))
+    lines.append(f'---')
+    lines.append(f'{nfunc} functions, {ncls} classes (via extract)')
+    print('\n'.join(lines))
+except:
+    pass
+" 2>/dev/null)
+  fi
+fi
+
+# Bypass: both context and extract failed or produced nothing useful
+if [ -z "$TLDR_OUTPUT" ]; then
+  exit 0
+fi
+
+# Also get the file's imports and format them
+TLDR_IMPORTS_RAW=$("$TLDR_BIN" imports "$REL_PATH" --lang "$TLDR_LANG" 2>/dev/null || true)
+TLDR_IMPORTS=""
+if [ -n "$TLDR_IMPORTS_RAW" ]; then
+  TLDR_IMPORTS=$(echo "$TLDR_IMPORTS_RAW" | python3 -c "
+import json, sys
+try:
+    data = json.load(sys.stdin)
+    lines = []
+    for imp in data:
+        mod = imp.get('module', '?')
+        names = imp.get('names', [])
+        default = imp.get('default')
+        parts = []
+        if default:
+            parts.append(default)
+        if names:
+            parts.append('{ ' + ', '.join(names) + ' }')
+        if parts:
+            lines.append(f'import {', '.join(parts)} from \"{mod}\"')
+        else:
+            lines.append(f'import \"{mod}\"')
+    print('\n'.join(lines))
+except:
+    # If JSON parsing fails, use raw output (may already be formatted)
+    sys.stdout.write(sys.stdin.read() if hasattr(sys, '_raw') else '')
+" 2>/dev/null)
+  # If Python formatting failed, fall back to raw
+  if [ -z "$TLDR_IMPORTS" ]; then
+    TLDR_IMPORTS="$TLDR_IMPORTS_RAW"
+  fi
+fi
+
+# Build the summary that Claude will see instead of the raw file
+SUMMARY="[TLDR Summary — ${FILE_SIZE} bytes saved from context]
+
+File: ${FILE_PATH}
+
+## Structure & Exports
+${TLDR_OUTPUT}"
+
+if [ -n "$TLDR_IMPORTS" ]; then
+  SUMMARY="${SUMMARY}
+
+## Imports
+${TLDR_IMPORTS}"
+fi
+
+SUMMARY="${SUMMARY}
+
+---
+To read the full file, use Read with offset/limit parameters for the specific section you need to edit."
+
+# Deny the read and provide TLDR context instead
+# Use a temp file for the JSON to handle multiline safely
+TEMP_JSON=$(mktemp /tmp/tldr-hook-XXXXXX.json)
+jq -n --arg reason "TLDR summary provided instead of full file read (${FILE_SIZE} bytes → ~1K tokens)" \
+      --arg context "$SUMMARY" \
+  '{
+    hookSpecificOutput: {
+      hookEventName: "PreToolUse",
+      permissionDecision: "deny",
+      permissionDecisionReason: $reason,
+      additionalContext: $context
+    }
+  }' > "$TEMP_JSON" 2>/dev/null
+
+cat "$TEMP_JSON"
+rm -f "$TEMP_JSON"
+
+exit 0

package/scripts/work-agent-stop-hook

@@ -0,0 +1,137 @@
+#!/bin/bash
+# ~/.panopticon/bin/work-agent-stop-hook
+# Called when any agent goes idle — detects work agents that forgot "pan work done"
+#
+# Uses a lightweight AI model to analyze the last N lines of terminal output
+# and determine if the agent completed its work but failed to signal completion.
+# If so, sends a nudge message to the agent via tmux.
+#
+# The model used is configurable via PANOPTICON_COMPLETION_CHECK_MODEL env var
+# or defaults to the models.overrides.completion-check-hook setting in config.yaml,
+# falling back to claude-haiku-4-5.
+
+# Don't use set -e - resilient to failures, never break Claude Code execution
+
+# Get agent ID
+if [ -n "$PANOPTICON_AGENT_ID" ]; then
+  AGENT_ID="$PANOPTICON_AGENT_ID"
+elif [ -n "$TMUX" ]; then
+  AGENT_ID=$(tmux display-message -p '#S' 2>/dev/null)
+else
+  exit 0
+fi
+
+# Only run for work agents (agent-min-XXX, agent-pan-XXX, etc.)
+case "$AGENT_ID" in
+  agent-*)
+    # Check it's not a specialist
+    case "$AGENT_ID" in
+      specialist-*) exit 0 ;;
+    esac
+    ;;
+  *)
+    exit 0  # Not a work agent
+    ;;
+esac
+
+# Extract issue ID from agent ID (e.g., "agent-min-725" -> "MIN-725")
+ISSUE_ID=$(echo "$AGENT_ID" | sed 's/^agent-//' | tr '[:lower:]' '[:upper:]')
+
+# Skip if completion marker already exists (agent already called pan work done)
+COMPLETED_FILE="$HOME/.panopticon/agents/$AGENT_ID/completed"
+if [ -f "$COMPLETED_FILE" ]; then
+  exit 0
+fi
+
+# Cooldown: don't nudge more than once per 10 minutes
+NUDGE_FILE="$HOME/.panopticon/agents/$AGENT_ID/.last-completion-nudge"
+if [ -f "$NUDGE_FILE" ]; then
+  LAST_NUDGE=$(cat "$NUDGE_FILE" 2>/dev/null || echo "0")
+  NOW=$(date +%s)
+  ELAPSED=$(( NOW - LAST_NUDGE ))
+  if [ "$ELAPSED" -lt 600 ]; then
+    exit 0  # Too soon since last nudge
+  fi
+fi
+
+# Capture the last 80 lines of terminal output
+OUTPUT=$(tmux capture-pane -t "$AGENT_ID" -p -S -80 2>/dev/null || echo "")
+if [ -z "$OUTPUT" ]; then
+  exit 0
+fi
+
+# Quick heuristic pre-check: skip the expensive AI call if the output clearly
+# shows the agent is mid-work (e.g., running tests, editing files, reading)
+if echo "$OUTPUT" | grep -qE '(Reading|Editing|Searching|Running|Compiling|Building|Installing|●.*Bash|●.*Read|●.*Edit|●.*Grep|●.*Write|●.*Glob)' | tail -5 | grep -qE '●'; then
+  exit 0
+fi
+
+# Check if the agent appears to be at an idle prompt (not mid-response)
+if ! echo "$OUTPUT" | tail -10 | grep -qE '(^❯|Worked for)'; then
+  exit 0  # Agent doesn't appear to be at an idle prompt
+fi
+
+# Determine model to use for completion check
+# Priority: env var > config.yaml override > default
+COMPLETION_MODEL="${PANOPTICON_COMPLETION_CHECK_MODEL:-}"
+if [ -z "$COMPLETION_MODEL" ]; then
+  CONFIG_FILE="$HOME/.panopticon/config.yaml"
+  if [ -f "$CONFIG_FILE" ] && command -v grep &> /dev/null; then
+    COMPLETION_MODEL=$(grep 'completion-check-hook:' "$CONFIG_FILE" 2>/dev/null | awk '{print $2}' | tr -d '"' || echo "")
+  fi
+fi
+COMPLETION_MODEL="${COMPLETION_MODEL:-claude-haiku-4-5}"
+
+# Build the analysis prompt
+ANALYSIS_PROMPT="You are analyzing a work agent's terminal output to determine if it finished its work but forgot to call 'pan work done'.
+
+The agent was working on issue $ISSUE_ID. Here is the last 80 lines of its terminal output:
+
+<terminal_output>
+$OUTPUT
+</terminal_output>
+
+Respond with EXACTLY one of these words (nothing else):
+- FORGOT_COMPLETION — if the agent clearly finished its implementation work (closed beads, committed code, ran tests) but stopped without calling 'pan work done'
+- STILL_WORKING — if the agent appears to have more work to do (mentioned next steps, was mid-task)
+- STOPPED_FOR_INPUT — if the agent stopped because it needs human input or hit a blocker
+- UNCLEAR — if you cannot determine the state"
+
+# Run the analysis using claude CLI (headless, no interactive session)
+RESULT=$(echo "$ANALYSIS_PROMPT" | claude -p --model "$COMPLETION_MODEL" --max-tokens 20 2>/dev/null || echo "UNCLEAR")
+
+# Extract just the verdict (first word of output, strip whitespace)
+VERDICT=$(echo "$RESULT" | tr -d '[:space:]' | head -c 30)
+
+# Log the check
+LOG_DIR="$HOME/.panopticon/logs"
+mkdir -p "$LOG_DIR"
+echo "[$(date -Iseconds)] work-agent-stop-hook: $AGENT_ID ($ISSUE_ID) -> $VERDICT (model: $COMPLETION_MODEL)" \
+  >> "$LOG_DIR/hooks.log" 2>/dev/null || true
+
+if [ "$VERDICT" = "FORGOT_COMPLETION" ]; then
+  # Record nudge timestamp for cooldown
+  mkdir -p "$(dirname "$NUDGE_FILE")"
+  date +%s > "$NUDGE_FILE" 2>/dev/null || true
+
+  # Write the nudge message to a temp file and use load-buffer + paste-buffer
+  # (the reliable tmux message delivery pattern from CLAUDE.md)
+  NUDGE_MSG="You stopped without calling pan work done. If your implementation is complete, you MUST run this command now:
+
+pan work done $ISSUE_ID -c \"Implementation complete\"
+
+If you still have remaining tasks, continue working on them. Do NOT stop until all work is done AND you have called pan work done."
+
+  TMPFILE=$(mktemp)
+  echo "$NUDGE_MSG" > "$TMPFILE"
+  tmux load-buffer "$TMPFILE" 2>/dev/null
+  tmux paste-buffer -t "$AGENT_ID" 2>/dev/null
+  sleep 0.3
+  tmux send-keys -t "$AGENT_ID" C-m 2>/dev/null
+  rm -f "$TMPFILE"
+
+  echo "[$(date -Iseconds)] work-agent-stop-hook: Sent completion nudge to $AGENT_ID" \
+    >> "$LOG_DIR/hooks.log" 2>/dev/null || true
+fi
+
+exit 0

package/skills/check-merged/SKILL.md

@@ -0,0 +1,143 @@
+---
+name: check-merged
+description: >
+  Verify whether an issue's feature branch has been merged into main.
+  Checks git history, branch existence, and commit presence. Returns
+  MERGED, NOT_MERGED, or BRANCH_NOT_FOUND with evidence.
+  Designed for cheap models (Haiku) to run quickly.
+tools: Bash(git:*)
+model: haiku
+---
+
+# Check Merged
+
+Verify whether a feature branch for an issue has been merged into the main branch.
+
+## Purpose
+
+After an issue reaches "Done" on the kanban board, we need to confirm the code was actually merged — not just that the tracker status was updated. This skill checks git evidence to give a definitive answer.
+
+## When to Use
+
+- **Close-out ceremony**: Before archiving workspace artifacts
+- **Done column audit**: Batch-verify all Done items are genuinely merged
+- **Stale branch cleanup**: Identify branches that were abandoned vs merged
+- **As a subagent**: Spawn from a parent agent to verify multiple issues in parallel
+
+## Input
+
+The skill expects an issue ID (e.g., `PAN-123`, `MIN-456`) and a project path.
+
+## Execution
+
+### Step 1: Resolve Branch Name
+
+```bash
+# Standard naming convention
+BRANCH="feature/${ISSUE_ID_LOWER}"
+
+# Also check alternate patterns
+# edwardbecker/${issue-slug} (Linear default)
+# feature/${issue-id}-description
+```
+
+### Step 2: Check If Branch Exists
+
+```bash
+# Check local branches
+git -C "$PROJECT_PATH" branch --list "$BRANCH" 2>/dev/null
+
+# Check remote branches
+git -C "$PROJECT_PATH" ls-remote --heads origin "$BRANCH" 2>/dev/null
+
+# Check Linear-style branch names (broader search)
+git -C "$PROJECT_PATH" branch -a --list "*${ISSUE_ID_LOWER}*" 2>/dev/null
+```
+
+### Step 3: Check Merge Evidence
+
+**If branch exists locally:**
+```bash
+# Check for unmerged commits
+git -C "$PROJECT_PATH" log main.."$BRANCH" --oneline 2>/dev/null
+# Empty output = fully merged
+# Non-empty = has unmerged commits
+```
+
+**If branch exists on remote only:**
+```bash
+git -C "$PROJECT_PATH" fetch origin "$BRANCH" 2>/dev/null
+git -C "$PROJECT_PATH" log main..origin/"$BRANCH" --oneline 2>/dev/null
+```
+
+**If no branch found (may be squash-merged and deleted):**
+```bash
+# Check if any commit in main references the issue ID
+git -C "$PROJECT_PATH" log main --oneline --grep="$ISSUE_ID" 2>/dev/null
+
+# Check merge commits
+git -C "$PROJECT_PATH" log main --oneline --merges --grep="$ISSUE_ID" 2>/dev/null
+
+# Check squash commits (PR title often contains issue ID)
+git -C "$PROJECT_PATH" log main --oneline --grep="$BRANCH" 2>/dev/null
+```
+
+### Step 4: Check PR Status (if gh available)
+
+```bash
+# Find closed/merged PRs for this branch
+gh pr list --repo OWNER/REPO --state merged --head "$BRANCH" --json number,title,mergedAt 2>/dev/null
+
+# Or search by issue reference
+gh pr list --repo OWNER/REPO --state merged --search "$ISSUE_ID" --json number,title,mergedAt 2>/dev/null
+```
+
+## Output Format
+
+Report one of three results:
+
+### MERGED
+```
+RESULT: MERGED
+ISSUE: PAN-123
+EVIDENCE:
+  - Branch: feature/pan-123 (deleted after merge)
+  - Commit: abc1234 "PAN-123: Implement feature X" found on main
+  - PR: #456 merged at 2026-02-15T10:30:00Z
+```
+
+### NOT_MERGED
+```
+RESULT: NOT_MERGED
+ISSUE: PAN-123
+EVIDENCE:
+  - Branch: feature/pan-123 exists with 3 unmerged commits
+  - Latest commit: def5678 "WIP: partial implementation"
+  - No merged PR found
+```
+
+### BRANCH_NOT_FOUND
+```
+RESULT: BRANCH_NOT_FOUND
+ISSUE: PAN-123
+EVIDENCE:
+  - No branch matching "feature/pan-123" or "*pan-123*" found
+  - No commits on main reference "PAN-123"
+  - No merged PRs reference "PAN-123"
+NOTE: Issue may have been completed without code changes, or branch name doesn't follow convention
+```
+
+## Polyrepo Support
+
+For polyrepo projects, check each repo in the project:
+
+```bash
+# Get repo list from project config
+# For each repo, run the same checks against that repo's path
+```
+
+## Error Handling
+
+- If `PROJECT_PATH` doesn't exist or isn't a git repo: report error immediately
+- If `git fetch` fails (network): report based on local evidence only, note the fetch failure
+- If `gh` CLI isn't available: skip PR check, report based on git evidence only