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

Invariant 1: the log_offset pattern

Agent logs append across attempts. agent.OffsetBefore records the file size before the agent runs; agent.ReadAfter reads only the new tail. BlockedLine and HasRateLimit operate on that tail.

Rule: never scan the full log file to detect failures. That re-detects failures from previous attempts and causes false positives (e.g. a ticket that was rate-limited on attempt 1 would be falsely detected as rate-limited on attempt 2 even when the agent succeeded).

Where it lives: internal/agent/log.go (OffsetBefore, ReadAfter), consumed in internal/pipeline/process.go and internal/pipeline/iterate.go.

Invariant 2: the noctra/ branch-prefix guardrail

The auto-iterate watcher identifies its own PRs by the noctra/<id> branch prefix. repo.BranchName generates it; github.ListNoctraPRs filters on it; watch and iterate depend on it.

Rules:

• Keep CreateWorktree and ResumeWorktree on the same prefix or the watcher silently never finds its own PRs.
• Never create a noctra/-prefixed branch for manual work or agent-assisted PRs in this repo. The watcher will claim it and push conflicting follow-up commits.
• Use fix/, feat/, docs/, chore/, or eng-<n>-<slug> prefixes for non-Noctra branches.

Invariant 3: backend-agnostic internal/agent split

Shared agent logic goes in the common code (backend.go, prompt.go); a backend file holds only its invocation args and rate-limit regex. Details and per-backend quirks: agent-backends.

Invariant 4: cursor semantics

The PR-watch system tracks what feedback has been acted on via cursors in internal/state:

• Comment/review cursors are timestamps (naturally ordered). Conversation comments and inline review-thread comments share the comment cursor.
• CI cursor is keyed by head commit SHA (LastCISHA) — acted on once per commit. A fix push changes the SHA, making a fresh failure on the new commit eligible again.

Rule: don't change cursor types or comparison logic without understanding that timestamps work for comments (monotonically increasing) but not for CI (where the same SHA can have multiple check runs; what matters is "have we already acted on this SHA?").

Invariant 5: pure functions for testability

Noctra follows a convention of extracting logic into pure, side-effect-free functions that are unit-tested independently from the I/O that calls them:

Rule: when adding new logic, prefer extracting the decision/formatting into a pure function with table-driven tests, then call it from the I/O layer. This keeps tests fast and deterministic.

Invariant 6: golangci-lint v2 syntax

The repo uses .golangci.yml with version: "2" syntax. This means:

• Linters are configured under linters.default and linters.settings, not the v1 linters.enable list.
• Formatters are under formatters.enable (e.g. gofmt), not mixed with linters.

Rule: if adding linter config, use v2 syntax. v1 keys will cause a parse error.

Invariant 7: the codebase carries no comments

Source files hold zero comments — the only exception is a compiler/tooling directive (//go:embed, //go:build, //nolint, // Code generated). Do not reintroduce explanatory comments, doc comments on exported symbols included. Names and structure carry the what; this file and CLAUDE.md carry the why.

The non-obvious facts that previously lived in comments, kept here so removing them lost nothing:

Invariant 8: where types live

A package's data model lives in its types.go: plain structs, interfaces, func types and enums (the named type plus its const block), together with trivial methods such as Error, String or Unwrap. A large set of wire types for one external API gets its own <source>_types.go (source/jira_types.go).

Three kinds stay beside their logic instead:

• a type that owns behaviour: a constructor plus real methods (Pipeline, Store, Server, claudeBackend, review.Result, agent.ModelPrices);
• an unexported enum with a single consumer (agentRunStatus next to classifyAgentRun);
• a small decode struct used by one function.

Go has no barrel or index files. Every file in a directory is already one package, so a re-exporting file adds nothing.

Quality gates

Before submitting changes:

go test ./...       # all tests must pass
go vet ./...        # must be clean

If golangci-lint is available:

golangci-lint run

These are the same checks CI runs. A PR that fails either will not be merged.