panopticon-cli 0.5.0 → 0.5.3

package/scripts/work-agent-stop-hook

@@ -2,9 +2,8 @@
 # ~/.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.
+# Uses evidence-based detection first (STATE.md, git, beads), then falls back to
+# a lightweight AI model for ambiguous cases. Writes resolution to runtime.json.
 #
 # 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,
@@ -37,14 +36,18 @@ 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:]')
 
+AGENT_STATE_DIR="$HOME/.panopticon/agents/$AGENT_ID"
+LOG_DIR="$HOME/.panopticon/logs"
+mkdir -p "$LOG_DIR"
+
 # Skip if completion marker already exists (agent already called pan work done)
-COMPLETED_FILE="$HOME/.panopticon/agents/$AGENT_ID/completed"
+COMPLETED_FILE="$AGENT_STATE_DIR/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"
+NUDGE_FILE="$AGENT_STATE_DIR/.last-completion-nudge"
 if [ -f "$NUDGE_FILE" ]; then
   LAST_NUDGE=$(cat "$NUDGE_FILE" 2>/dev/null || echo "0")
   NOW=$(date +%s)
@@ -54,15 +57,151 @@ if [ -f "$NUDGE_FILE" ]; then
   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
+# ============================================================================
+# Helper: write resolution to runtime.json
+# ============================================================================
+write_resolution() {
+  local resolution="$1"
+  local runtime_file="$AGENT_STATE_DIR/runtime.json"
+
+  # Read existing resolution count
+  local existing_count=0
+  local existing_resolution=""
+  if [ -f "$runtime_file" ]; then
+    existing_resolution=$(python3 -c "import json,sys; d=json.load(open('$runtime_file')); print(d.get('resolution',''))" 2>/dev/null || echo "")
+    existing_count=$(python3 -c "import json,sys; d=json.load(open('$runtime_file')); print(d.get('resolutionCount',0))" 2>/dev/null || echo "0")
+  fi
+
+  # Increment count if same resolution, reset if changed
+  local new_count
+  if [ "$existing_resolution" = "$resolution" ]; then
+    new_count=$(( existing_count + 1 ))
+  else
+    new_count=1
+  fi
+
+  local now_iso
+  now_iso=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+
+  # Merge into runtime.json using python3 (jq not always available)
+  python3 - <<PYEOF 2>/dev/null || true
+import json, os
+
+runtime_file = "$runtime_file"
+resolution = "$resolution"
+new_count = $new_count
+now_iso = "$now_iso"
+
+# Read existing
+data = {}
+if os.path.exists(runtime_file):
+    try:
+        with open(runtime_file) as f:
+            data = json.load(f)
+    except Exception:
+        pass
+
+# Update resolution fields
+data['resolution'] = resolution
+data['resolutionCount'] = new_count
+data['resolutionUpdatedAt'] = now_iso
+
+# Write back
+with open(runtime_file, 'w') as f:
+    json.dump(data, f, indent=2)
+PYEOF
+
+  echo "[$(date -Iseconds)] work-agent-stop-hook: $AGENT_ID resolution=$resolution count=$new_count" \
+    >> "$LOG_DIR/hooks.log" 2>/dev/null || true
+}
+
+# ============================================================================
+# Phase 1: Evidence-Based Completion Detection
+# ============================================================================
+
+# Read workspace path from state.json
+WORKSPACE=""
+STATE_FILE="$AGENT_STATE_DIR/state.json"
+if [ -f "$STATE_FILE" ]; then
+  WORKSPACE=$(python3 -c "import json; d=json.load(open('$STATE_FILE')); print(d.get('workspace',''))" 2>/dev/null || echo "")
+fi
+
+STATE_MD_COMPLETE=false
+BRANCH_PUSHED=false
+BEADS_CLOSED=false
+
+# Check 1: STATE.md completion markers
+if [ -n "$WORKSPACE" ] && [ -f "$WORKSPACE/.planning/STATE.md" ]; then
+  if grep -qiE '(^##?\s*(Status|Current Status).*:.*\b(COMPLETE|DONE|FINISHED)\b|^Status:\s*(COMPLETE|DONE|FINISHED)|implementation[[:space:]]+complete|all[[:space:]]+tasks[[:space:]]+complete)' "$WORKSPACE/.planning/STATE.md" 2>/dev/null; then
+    STATE_MD_COMPLETE=true
+  fi
+fi
+
+# Check 2: Branch pushed to remote (git log origin/<branch>..HEAD is empty)
+if [ -n "$WORKSPACE" ] && [ -d "$WORKSPACE/.git" ] || ([ -n "$WORKSPACE" ] && git -C "$WORKSPACE" rev-parse --git-dir >/dev/null 2>&1); then
+  BRANCH=$(git -C "$WORKSPACE" branch --show-current 2>/dev/null || echo "")
+  if [ -n "$BRANCH" ]; then
+    UNPUSHED=$(git -C "$WORKSPACE" log "origin/$BRANCH..HEAD" --oneline 2>/dev/null || echo "no-remote")
+    if [ "$UNPUSHED" = "" ]; then
+      BRANCH_PUSHED=true
+    fi
+  fi
+fi
+
+# Check 3: Beads closed (all tasks done)
+if [ -n "$WORKSPACE" ] && [ -d "$WORKSPACE/.planning/beads" ]; then
+  OPEN_BEADS=$(bd list --status open 2>/dev/null | grep -c '.' || echo "0")
+  if [ "$OPEN_BEADS" = "0" ]; then
+    BEADS_CLOSED=true
+  fi
+elif [ -z "$WORKSPACE" ] || [ ! -d "$WORKSPACE/.planning/beads" ]; then
+  # No beads directory = treat as N/A (closed)
+  BEADS_CLOSED=true
+fi
+
+# Apply decision matrix from spec
+if [ "$STATE_MD_COMPLETE" = "true" ] && [ "$BRANCH_PUSHED" = "true" ]; then
+  # Strong evidence: agent completed but forgot pan work done
+  echo "[$(date -Iseconds)] work-agent-stop-hook: $AGENT_ID evidence=FORGOT_COMPLETION (STATE.md=complete, branch=pushed, beads=$BEADS_CLOSED)" \
+    >> "$LOG_DIR/hooks.log" 2>/dev/null || true
+
+  write_resolution "done"
+
+  # Record nudge timestamp for cooldown
+  mkdir -p "$AGENT_STATE_DIR"
+  date +%s > "$NUDGE_FILE" 2>/dev/null || true
+
+  NUDGE_MSG="Your STATE.md indicates work is complete and your branch is pushed. 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 FORGOT_COMPLETION nudge to $AGENT_ID" \
+    >> "$LOG_DIR/hooks.log" 2>/dev/null || true
+
+  exit 0
+
+elif [ "$STATE_MD_COMPLETE" = "true" ] && [ "$BRANCH_PUSHED" = "false" ]; then
+  # STATE.md says done but branch not yet pushed — agent is still working (pushing)
+  echo "[$(date -Iseconds)] work-agent-stop-hook: $AGENT_ID evidence=STILL_WORKING (STATE.md=complete, branch=not-pushed)" \
+    >> "$LOG_DIR/hooks.log" 2>/dev/null || true
   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
+# ============================================================================
+# Heuristic pre-check: skip expensive AI call if clearly mid-work
+# ============================================================================
+OUTPUT=$(tmux capture-pane -t "$AGENT_ID" -p -S -80 2>/dev/null || echo "")
+if [ -z "$OUTPUT" ]; then
   exit 0
 fi
 
@@ -71,8 +210,9 @@ 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
+# ============================================================================
+# LLM fallback for ambiguous cases
+# ============================================================================
 COMPLETION_MODEL="${PANOPTICON_COMPLETION_CHECK_MODEL:-}"
 if [ -z "$COMPLETION_MODEL" ]; then
   CONFIG_FILE="$HOME/.panopticon/config.yaml"
@@ -82,7 +222,33 @@ if [ -z "$COMPLETION_MODEL" ]; then
 fi
 COMPLETION_MODEL="${COMPLETION_MODEL:-claude-haiku-4-5}"
 
-# Build the analysis prompt
+# Read current resolution count from runtime.json for escalation logic
+CURRENT_RESOLUTION=$(python3 -c "
+import json, os
+f = '$AGENT_STATE_DIR/runtime.json'
+if os.path.exists(f):
+    try:
+        d = json.load(open(f))
+        print(d.get('resolution', ''))
+    except Exception:
+        print('')
+else:
+    print('')
+" 2>/dev/null || echo "")
+
+CURRENT_COUNT=$(python3 -c "
+import json, os
+f = '$AGENT_STATE_DIR/runtime.json'
+if os.path.exists(f):
+    try:
+        d = json.load(open(f))
+        print(d.get('resolutionCount', 0))
+    except Exception:
+        print(0)
+else:
+    print(0)
+" 2>/dev/null || echo "0")
+
 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:
@@ -97,25 +263,19 @@ Respond with EXACTLY one of these words (nothing else):
 - 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
+  write_resolution "done"
+
   # Record nudge timestamp for cooldown
-  mkdir -p "$(dirname "$NUDGE_FILE")"
+  mkdir -p "$AGENT_STATE_DIR"
   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\"
@@ -130,8 +290,45 @@ If you still have remaining tasks, continue working on them. Do NOT stop until a
   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" \
+  echo "[$(date -Iseconds)] work-agent-stop-hook: Sent FORGOT_COMPLETION nudge to $AGENT_ID" \
     >> "$LOG_DIR/hooks.log" 2>/dev/null || true
+
+elif [ "$VERDICT" = "STOPPED_FOR_INPUT" ]; then
+  write_resolution "needs_input"
+
+elif [ "$VERDICT" = "UNCLEAR" ]; then
+  # Escalate to stuck after 2+ UNCLEAR results
+  if [ "$CURRENT_RESOLUTION" = "unclear" ] || [ "$CURRENT_COUNT" -ge 2 ]; then
+    write_resolution "stuck"
+    echo "[$(date -Iseconds)] work-agent-stop-hook: $AGENT_ID escalated to stuck after $CURRENT_COUNT UNCLEAR results" \
+      >> "$LOG_DIR/hooks.log" 2>/dev/null || true
+  else
+    # First UNCLEAR — track it but don't escalate yet
+    python3 - <<PYEOF 2>/dev/null || true
+import json, os
+
+runtime_file = "$AGENT_STATE_DIR/runtime.json"
+data = {}
+if os.path.exists(runtime_file):
+    try:
+        with open(runtime_file) as f:
+            data = json.load(f)
+    except Exception:
+        pass
+
+existing = data.get('resolution', '')
+count = data.get('resolutionCount', 0)
+if existing == 'unclear':
+    data['resolutionCount'] = count + 1
+else:
+    data['resolution'] = 'unclear'
+    data['resolutionCount'] = 1
+data['resolutionUpdatedAt'] = "$(date -u +"%Y-%m-%dT%H:%M:%SZ")"
+
+with open(runtime_file, 'w') as f:
+    json.dump(data, f, indent=2)
+PYEOF
+  fi
 fi
 
 exit 0

package/skills/pan-new-project/SKILL.md

@@ -0,0 +1,304 @@
+---
+name: pan-new-project
+description: >
+  Complete setup for registering a new project with Panopticon. Handles
+  project registration, issue prefix, workspace config, trust setup,
+  beads init, tracker config, and validates against working projects.
+triggers:
+  - new project
+  - add new project
+  - register new project
+  - setup new project
+  - onboard project
+  - pan new project
+allowed-tools:
+  - Bash
+  - Read
+  - Edit
+  - Write
+  - Glob
+  - Grep
+  - AskUserQuestion
+version: "2.0.0"
+author: "Ed Becker"
+license: "MIT"
+---
+
+# New Project Setup
+
+**Trigger:** `/pan-new-project`
+
+Sets up a new project for Panopticon management. This is the ONLY correct
+way to add a new project. Do NOT just run `pan project add` alone — it
+creates a skeleton entry that breaks planning agents, workspace creation,
+issue routing, and beads.
+
+---
+
+## WHY THIS SKILL EXISTS
+
+Running `pan project add /path --name foo` alone causes these failures:
+
+| Missing config | Symptom |
+|----------------|---------|
+| `linear_team` (issue prefix) | Planning agents start in `$HOME`, not the project root |
+| Trust entry in `~/.claude.json` | Claude Code shows trust dialog, blocking autonomous agents |
+| `GITHUB_REPOS` entry | Issues don't appear on the dashboard kanban board |
+| `beads.role` in git config | Every `bd` command prints "beads.role not configured" warnings |
+| `workspaces/` directory | Git worktree creation fails |
+| `.gitignore` entry | `workspaces/` gets committed accidentally |
+| Test config | Specialist test agents can't run tests |
+
+---
+
+## EXECUTION STEPS
+
+### Step 1: Gather Project Information
+
+Ask the user for (or auto-detect from the filesystem):
+
+| Field | Required | Example | Notes |
+|-------|----------|---------|-------|
+| Path | Yes | `/home/eltmon/Projects/myapp` | Must exist, must have `.git/` |
+| Name | Yes | `myapp` | Short lowercase key for projects.yaml |
+| Issue prefix | Yes | `APP` | Maps `APP-123` → this project. Goes in `linear_team` field |
+| Tracker | Yes | `github` / `linear` / `gitlab` | Where issues live |
+| Repo slug | Yes | `owner/repo` | `github_repo` or `gitlab_repo` |
+| Workspace type | Yes | `standalone` / `monorepo` / `polyrepo` | How git worktrees work |
+
+**Auto-detection:**
+- `go.mod` → Go, test: `make test` or `go test ./...`
+- `package.json` → Node/TS, test: `npm test` or `pnpm test`
+- `pom.xml` / `mvnw` → Java/Maven, test: `./mvnw test`
+- `Cargo.toml` → Rust, test: `cargo test`
+- `pyproject.toml` → Python, test: `pytest`
+
+### Step 2: Register Project
+
+```bash
+pan project add <path> --name <name>
+```
+
+This creates a minimal entry AND pre-trusts the directory in `~/.claude.json`
+(the `projectAddCommand` calls `preTrustDirectory` automatically).
+
+### Step 3: Configure projects.yaml
+
+Edit `~/.panopticon/projects.yaml` to add the FULL configuration.
+
+**Minimum viable config:**
+
+```yaml
+  <project-key>:
+    name: <name>
+    path: <absolute-path>
+    linear_team: <PREFIX>          # CRITICAL: issue prefix for routing
+    github_repo: <owner/repo>     # or gitlab_repo
+    workspace:
+      type: <standalone|monorepo|polyrepo>
+      workspaces_dir: workspaces
+      default_branch: main
+    tests:
+      unit:
+        type: <go|vitest|maven|pytest|cargo>
+        path: .
+        command: <test command>
+```
+
+**Full config** (for projects with services, Docker, DNS):
+
+```yaml
+  <project-key>:
+    name: <name>
+    path: <absolute-path>
+    linear_team: <PREFIX>
+    github_repo: <owner/repo>
+    workspace:
+      type: <type>
+      workspaces_dir: workspaces
+      default_branch: main
+      dns:
+        domain: <name>.localhost
+        entries:
+          - "{{FEATURE_FOLDER}}.{{DOMAIN}}"
+        sync_method: hosts_file
+      docker:
+        traefik: templates/traefik
+        compose_template: infra/.devcontainer-template
+      agent:
+        template_dir: infra/.agent-template
+        copy_dirs:
+          - .claude/commands
+          - .claude/skills
+      services:
+        - name: <service>
+          path: .
+          start_command: <cmd>
+          health_url: <url>
+          port: <port>
+      env:
+        secrets_file: ~/.myapp/.env
+    tests:
+      unit:
+        type: <type>
+        path: .
+        command: <cmd>
+```
+
+### Step 4: Add to Dashboard Tracker Config
+
+For **GitHub** projects, add to `GITHUB_REPOS` in `~/.panopticon.env`:
+
+```bash
+# Format: owner/repo:PREFIX (comma-separated)
+# Example: current value might be:
+#   GITHUB_REPOS=eltmon/panopticon-cli:PAN
+# Append the new project:
+#   GITHUB_REPOS=eltmon/panopticon-cli:PAN,owner/newrepo:APP
+```
+
+Read current value, append new repo, write back. The dashboard polls this
+to fetch issues from GitHub.
+
+For **Linear** projects, issues are fetched automatically by team — no
+extra config needed beyond `linear_team` in projects.yaml.
+
+For **GitLab** projects, TBD — not yet supported in dashboard polling.
+
+### Step 5: Initialize Beads
+
+```bash
+cd <project-path>
+git config beads.role agent
+```
+
+This prevents the `"beads.role not configured"` warning on every `bd` command.
+New worktrees inherit this automatically since Panopticon now sets it during
+workspace creation (`workspace-manager.ts` and `worktree.ts`).
+
+### Step 6: Create workspaces/ Directory
+
+```bash
+mkdir -p <project-path>/workspaces
+```
+
+Check `.gitignore` — add `workspaces/` if not already there:
+```bash
+grep -q '^workspaces/' <project-path>/.gitignore 2>/dev/null || \
+  echo 'workspaces/' >> <project-path>/.gitignore
+```
+
+### Step 7: Create CLAUDE.md (if missing)
+
+Check if the project has a `CLAUDE.md`. If not, create a minimal one:
+
+```markdown
+# <Project Name>
+
+## Project Overview
+<Brief description>
+
+## Stack
+<Language, framework, key dependencies>
+
+## Development
+<How to build, run, test>
+
+## Testing
+<Test commands, coverage requirements>
+```
+
+### Step 8: Validate Configuration
+
+Run ALL of these checks and report pass/fail:
+
+```bash
+# 1. Project registered
+pan project list | grep <name>
+
+# 2. Issue prefix resolves (won't crash)
+# Check projects.yaml has linear_team: <PREFIX>
+
+# 3. Trust is set in ~/.claude.json
+node -e "
+const d=JSON.parse(require('fs').readFileSync(
+  require('os').homedir()+'/.claude.json','utf8'));
+console.log(d.projects?.['<path>']?.hasTrustDialogAccepted
+  ? 'PASS: trusted' : 'FAIL: not trusted');
+"
+
+# 4. Dashboard can see issues (GitHub only)
+grep 'GITHUB_REPOS' ~/.panopticon.env | grep -q '<PREFIX>' && \
+  echo "PASS: in GITHUB_REPOS" || echo "FAIL: not in GITHUB_REPOS"
+
+# 5. Beads configured
+cd <path> && git config beads.role && echo "PASS" || echo "FAIL: beads.role not set"
+
+# 6. workspaces/ exists
+test -d <path>/workspaces && echo "PASS" || echo "FAIL: no workspaces/"
+
+# 7. workspaces/ in .gitignore
+grep -q 'workspaces' <path>/.gitignore 2>/dev/null && \
+  echo "PASS" || echo "FAIL: workspaces/ not in .gitignore"
+
+# 8. CLAUDE.md exists
+test -f <path>/CLAUDE.md && echo "PASS" || echo "WARN: no CLAUDE.md"
+
+# 9. Git clean
+cd <path> && git status --short | head -5
+```
+
+### Step 9: Summary
+
+```
+## New Project Setup Complete: <NAME>
+
+Path:           <path>
+Issue prefix:   <PREFIX> (e.g., <PREFIX>-1, <PREFIX>-42)
+Tracker:        GitHub (<owner/repo>)
+Workspace type: <type>
+Tests:          <command>
+Trusted:        Yes
+Beads:          Configured
+Dashboard:      Issues visible
+
+Validation: 8/8 checks passed
+
+Next steps:
+  1. Create issues on <tracker>
+  2. Run: pan opus-plan <PREFIX>-<N>  (plan with Opus)
+  3. Run: pan work issue <PREFIX>-<N> (spawn implementation agent)
+```
+
+---
+
+## REFERENCE: Working Project Configs
+
+### panopticon-cli (monorepo, GitHub)
+- `linear_team: PAN`, `github_repo: eltmon/panopticon-cli`
+- `workspace.type: monorepo`
+- Has: dns, docker, agent, services, env, tests
+
+### mind-your-now (polyrepo, Linear/GitLab)
+- `linear_team: MIN`, `gitlab_repo: eltmon/mind-your-now`
+- `workspace.type: polyrepo` with 6 sub-repos
+- Has: dns, docker, database, agent, services, tunnel, hume, env, tests
+
+### myn-cli (standalone, GitHub)
+- `linear_team: CLI`, `github_repo: mindyournow/myn-cli`
+- `workspace.type: standalone`
+- Has: tests
+
+---
+
+## COMMON MISTAKES
+
+1. **Missing `linear_team`** — The #1 cause of "planning agent starts in $HOME."
+   Despite the name, this field is the issue PREFIX for ALL trackers, not just Linear.
+2. **Not in `GITHUB_REPOS`** — Issues don't appear on dashboard kanban board.
+3. **No `beads.role`** — Every `bd` command prints warning noise in agent output.
+4. **Not pre-trusting the directory** — Agent gets stuck on trust dialog.
+5. **Wrong `workspace.type`** — `standalone` = single repo, `monorepo` = one repo with
+   worktrees, `polyrepo` = multiple repos under one parent dir.
+6. **Missing `workspaces/` directory** — Git worktree creation fails.
+7. **Missing `.gitignore` entry** — `workspaces/` gets committed accidentally.