71 lines
2.7 KiB
Markdown
71 lines
2.7 KiB
Markdown
# 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 template.
|
|
- Test command.
|
|
- 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
|
|
|
|
1. Only open issues; pull requests are excluded.
|
|
2. An issue assigned to another actor is ineligible.
|
|
3. Explicit issue number wins when eligible.
|
|
4. Otherwise sort by priority label (`P0`, `P1`, `P2`, unlabeled) then issue number.
|
|
5. 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 command receives issue number, title, body, repo, and branch through template fields and environment variables.
|
|
- 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
|
|
|
|
1. Priority selection chooses P0 before lower-priority tickets.
|
|
2. Tickets assigned to another human/agent are skipped.
|
|
3. Claim must be verified from Gitea before execution.
|
|
4. Agent failure stops the run before tests.
|
|
5. Test failure stops push and PR creation.
|
|
6. Passing tests produce a linked PR request with evidence.
|
|
7. Existing state/PR prevents duplicate work.
|
|
8. Dry-run against live Gitea returns a plan and performs no mutation.
|