architecturelisted

# Architecture & Contributing Use this playbook before changing Noctra's core code. The invariants below are easy to violate in a plausible-looking patch; each has caused a real bug or regression. ## Package map (navigation aid) | Package | Purpose | |---------|---------| | `cmd/noctra` | Entry point, subcommand dispatch, startup banner | | `internal/config` | `.env` parser, validated `Config`, `DefaultConfigDir` | | `internal/linear` | Linear GraphQL client (trigger queries, state/label mutations, comments, Telegram read queries) | | `internal/repo` | Repo resolution (`ResolveDirect` / `Resolve`), clone-on-demand, worktree create/resume/cleanup, `BranchName` | | `internal/agent` | Pluggable coding-agent backends, shared prompt builders, log_offset helpers, `BlockedLine`, `ExtractSummary` | | `internal/review` | Optional Gemini second-model review gate | | `internal/notify` | Optional Telegram notifier (fire-and-forget) | | `internal/telegram` | Inbound Telegram listener (long-polling, command dispatch) | | `internal/github` | Thin `gh` CLI wrapper (`ListNoctraPRs`, `GetPR`, `CheckLogs`) | | `internal/state` | File-backed PR cursor store (`~/.noctra-state.json`) | | `internal/watch` | Side-effect-free PR classifier (diffs feedback + CI against cursor) | | `internal/pipeline` | Poll loop, worker pool, per-ticket lifecycle (`process.go`), PR-watch + iterate (`iterate.go`), Telegram commands (`commands.go`) | | `internal/setup` | Interactive setup wizard | | `internal/cleanup