Feature Description

Add a read-only-first GitHub bridge for Hermes Kanban so Hermes can monitor linked GitHub issues/PRs/checks without making GitHub a competing task source of truth.

Motivation

Hermes Kanban is the canonical internal execution/control plane. GitHub is the public collaboration and upstream artifact layer.

We need integration between them, but the safe architectural boundary is:

Hermes Kanban = internal task truth
GitHub Issues/PRs = external collaboration/upstream state
Bridge = metadata sync and status monitor, not a replacement planner

This would help with workflows like:

• Track PR CI/review status from a Kanban card.
• Link a Kanban task to a GitHub issue or PR.
• Surface action-required CI states.
• Attach worker logs/test summaries to PR comments when explicitly requested.
• Close or unblock Kanban cards when upstream PRs merge.

Proposed Phases

Phase 1: Read-only import/monitoring

• Configure watched repositories.
• Link existing Kanban cards to GitHub issue/PR URLs.
• Poll or webhook GitHub state into Kanban metadata/comments:
  • PR open/closed/merged
  • mergeability
  • review decision
  • check suite status
  • action_required state for fork PR workflows
• No automatic writes to GitHub.

Phase 2: Explicit outbound comments

• Allow a user/agent to explicitly post:
  • local test summary
  • worker log summary
  • review-required status
  • CI diagnosis
• Require an explicit command/action for GitHub writes.
• Redact secrets before any outbound comment.

Phase 3: Card lifecycle integration

• If linked PR merges, mark card ready for verification or done depending on card policy.
• If linked PR closes unmerged, block or reopen the card with reason.
• If CI fails, move/keep card blocked with check-run evidence.

Phase 4: Optional issue/PR creation from Kanban

• Promote a Kanban finding into a GitHub issue.
• Promote a branch/worktree into a PR.
• Keep generated issue/PR URL stored in card metadata.

Non-Goals

• Do not replace Hermes Kanban with GitHub Projects.
• Do not make GitHub Issues the internal task queue.
• Do not automatically post internal logs to GitHub without explicit consent.
• Do not run arbitrary code from GitHub webhooks.

Safety / Security Requirements

• Secret redaction before any GitHub write.
• Read-only default token scope where possible.
• Explicit per-repo allowlist.
• Webhook signatures verified if webhook mode is supported.
• Rate-limit and backoff behavior for polling.
• Clear audit trail in Kanban comments/metadata.

Acceptance Criteria

• A Kanban card can store a linked GitHub issue/PR URL.
• Hermes can refresh and display GitHub state for linked cards.
• Fork PR action_required workflow state is detected and surfaced.
• No GitHub write occurs unless explicitly requested.
• The bridge preserves Hermes Kanban as the single internal source of truth.