Autonomous Issue-to-Release Engine — MVP Specification

Linked issue: stackchain/stackchain-dashboard#14

Purpose

Convert one eligible Gitea issue into a tested, traceable pull request without duplicate claims, unverified merges, or release spam.

Inputs

Gitea API base URL and token from environment.
Repository key (owner/repo).
Agent username.
Optional explicit issue number; otherwise deterministic queue selection.
Coding-agent command, parsed into an argument vector.
Test command, parsed into an argument vector.
Local repository path and durable state-file path.

State machine

discovered → claimed → agent_complete → tests_passed → pushed → pr_opened

Terminal failure states are claim_failed, agent_failed, tests_failed, and push_failed. A rerun resumes from persisted state and never opens a duplicate PR.

Queue selection

Only open issues; pull requests are excluded.
An issue assigned to another actor is ineligible.
Explicit issue number wins when eligible.
Otherwise sort by priority label (P0, P1, P2, unlabeled) then issue number.
Select exactly one issue per invocation.

Claiming

PATCH the issue with the configured assignee.
GET the issue and verify the live assignee matches.
Abort before code execution if verification fails.

Execution

Branch format: <agent>/<issue>-<slug>.
Coding and test commands are parsed with POSIX argument quoting and executed directly without a shell.
Issue number, title, body, repo, and branch are supplied to the coding agent only through RELEASE_ISSUE_NUMBER, RELEASE_ISSUE_TITLE, RELEASE_ISSUE_BODY, RELEASE_REPO, and RELEASE_BRANCH environment variables. Gitea-controlled content is never interpolated into executable syntax.
Shell operators, substitutions, and pipelines are not interpreted. Operators that are intentionally required must live in a separately reviewed wrapper script configured as the command.
Empty or malformed commands abort before the issue claim.
Non-zero coding-agent exit blocks tests and PR creation.
Tests run using the configured command; stdout/stderr and exit code become evidence.

PR and release gate

Push only after tests pass.
PR body includes Closes #N, test command, and evidence summary.
Existing open PR for the same head branch is reused.
The MVP does not auto-merge. CI plus human/agent review is the release gate.
Existing main-branch workflow drafts the release candidate after merge.

Safety and idempotency

--dry-run performs discovery and planning only: no claim, git mutation, agent command, push, or PR.
State is written atomically after each successful transition.
One invocation handles at most one issue.
Missing token, dirty worktree, failed claim verification, failed tests, or missing evidence blocks PR creation.

Acceptance tests

Priority selection chooses P0 before lower-priority tickets.
Tickets assigned to another human/agent are skipped.
Claim must be verified from Gitea before execution.
Agent failure stops the run before tests.
Test failure stops push and PR creation.
Passing tests produce a linked PR request with evidence.
Existing state/PR prevents duplicate work.
Dry-run against live Gitea returns a plan and performs no mutation.

3.3 KiB Raw Blame History