---
domain: global
category: pitfall
version: 1
last_updated: "2026-04-13"
---

# Pitfalls (Global)

Cross-repo traps that waste time across the fleet.

## Git & Forge

- id: global:pitfall:001
  fact: "Branch protection requires 1 approval on main - API merges fail with 405 without it"
  confidence: 0.95
  tags: [git, merge, branch-protection, gitea]
  source_count: 12
  first_seen: "2026-04-05"
  last_confirmed: "2026-04-13"
  related: [the-nexus:pitfall:001]

- id: global:pitfall:002
  fact: "Never use --no-verify on git commits - it bypasses all hooks including safety checks"
  confidence: 0.95
  tags: [git, hooks, safety]
  source_count: 5
  first_seen: "2026-03-28"
  last_confirmed: "2026-04-13"

- id: global:pitfall:003
  fact: "Gitea PR creation workaround needed on the-nexus - direct API call fails, use alternative endpoint"
  confidence: 0.9
  tags: [gitea, pr, api, workaround]
  source_count: 4
  first_seen: "2026-04-06"
  last_confirmed: "2026-04-12"

## Agent Operations

- id: global:pitfall:004
  fact: "Anthropic is BANNED from fallback chain - if fallback triggers to Anthropic, something is wrong"
  confidence: 0.95
  tags: [provider, anthropic, fallback]
  source_count: 7
  first_seen: "2026-03-30"
  last_confirmed: "2026-04-13"

- id: global:pitfall:005
  fact: "Telegram tokens expired - don't assume Telegram notifications work without checking"
  confidence: 0.85
  tags: [telegram, notifications, token]
  source_count: 3
  first_seen: "2026-04-02"

- id: global:pitfall:006
  fact: "Multiple gateways = 'cannot schedule futures' error - only one gateway process should run"
  confidence: 0.9
  tags: [gateway, cron, process]
  source_count: 4
  first_seen: "2026-04-04"
  last_confirmed: "2026-04-11"

## Testing

- id: global:pitfall:007
  fact: "pytest root collection picks up operational *_test.py scripts - restrict to tests/ directory"
  confidence: 0.9
  tags: [pytest, test, collection]
  source_count: 3
  first_seen: "2026-04-07"
  last_confirmed: "2026-04-13"

- id: global:pitfall:008
  fact: "TDD: test 1 before building 55 - verify the cycle works before scaling"
  confidence: 0.95
  tags: [tdd, testing, methodology]
  source_count: 8
  first_seen: "2026-03-25"
  last_confirmed: "2026-04-13"