devops-skills/docs/superpowers/specs/2026-03-13-gitea-agentic-runtime-design.md

# Gitea Agentic Runtime Design

**Date:** 2026-03-13  
**Status:** Approved for implementation  
**Scope:** Gitea single-platform real acceptance, with provider boundaries that keep later GitHub support incremental instead of invasive.

## Goal

Upgrade `gitea-issue-devops-agent` from a documentation-heavy delivery skill into a controlled execution subsystem that can:

- parse repository-local workflow specs
- compile and validate those specs into a locked execution plan
- run a Gitea-triggered issue workflow under hard policies
- persist plan and evidence artifacts
- pass automated unit, integration, and real Gitea acceptance checks

The external workflow remains:

`Issue -> Plan -> Branch -> Draft PR -> Preview -> Test Loop -> Human Merge`

The internal workflow gains a deterministic control plane.

## Why This Design

The repository currently has strong delivery guidance, but not a runtime that enforces it. `gh-aw` demonstrates the value of turning natural-language workflow definitions into constrained executable automations. We do not want to clone GitHub-native product shape. We do want equivalent execution discipline:

- a spec format users can author
- a compiler/validator that rejects unsafe or incomplete workflows
- a provider layer for platform APIs
- hard policy checks before write actions
- run evidence suitable for audit and acceptance

This keeps the product positioned as an enterprise AI DevOps control layer, not a GitHub Actions clone.

## In Scope

- Gitea provider
- workflow spec parsing
- compilation into lock artifacts
- validation of triggers, permissions, safe outputs, edit scope, and evidence contract
- runtime execution for selected issue flows
- safe output enforcement for Gitea writes
- evidence persistence
- CLI entrypoints for compile, validate, run, and acceptance
- automated tests
- one real Gitea acceptance path

## Out of Scope

- GitHub provider implementation
- autonomous queue-wide issue fixing
- automatic merge
- hosted webhook service
- UI control plane
- inference cost dashboards

## Architecture

### 1. Workflow Spec

Workflow specs live in-repo and use frontmatter plus Markdown body:

- frontmatter defines triggers, provider, permissions, safe outputs, required evidence, and policy defaults
- body captures workflow intent, operator notes, and execution hints

The spec is the source of truth. Runtime behavior never depends on free-form Markdown alone.

### 2. Compiler

The compiler loads a workflow spec and emits a lock artifact:

- normalizes defaults
- expands trigger shorthand into explicit configuration
- resolves safe output declarations into executable policy objects
- records required evidence and path scope

The lock artifact is immutable input to runtime. It is designed as JSON in this iteration because JSON is easy to diff, assert in tests, and consume from Python.

### 3. Validator

Validation rejects unsafe or incomplete specs before runtime:

- unsupported trigger combinations
- missing provider
- unsafe write permissions
- missing safe outputs for write behaviors
- invalid path scope syntax
- missing evidence requirements

This is the first hard boundary between intent and execution.

### 4. Runtime

Runtime consumes:

- a compiled lock artifact
- an event payload
- provider configuration and credentials

Runtime responsibilities:

- load and sanitize issue-trigger context
- initialize or update the persisted plan state
- enforce policy gates before any write action
- call provider APIs through a narrow interface
- collect evidence and write run artifacts

The runtime is not a general autonomous coding engine in this iteration. It is a control and orchestration layer for issue delivery actions.

### 5. Provider Layer

Provider interfaces isolate platform behavior from workflow logic.

The first provider is `GiteaProvider`, which supports:

- repository metadata reads
- issue reads
- issue comments
- branch hint extraction inputs
- draft PR preparation primitives

The abstraction must make later `GitHubProvider` addition additive rather than structural.

### 6. Policy and Safe Outputs

The policy layer turns delivery rules into code:

- read-only by default
- no merge action
- comment/create/update operations only if declared in safe outputs
- path-scope enforcement for file writes
- evidence-required status promotion
- bounded output counts where relevant

This is the key product maturity improvement over pure skill text.

### 7. Evidence Layer

Every run produces durable artifacts:

- resolved plan state
- execution summary
- provider operations executed
- evidence bundle for commit/PR/test/preview placeholders
- acceptance result metadata

Evidence is stored locally under a deterministic run directory so tests and operators can inspect it.

## File Structure

New code will be added under:

- `pyproject.toml`
- `engine/devops_agent/__init__.py`
- `engine/devops_agent/spec.py`
- `engine/devops_agent/compiler.py`
- `engine/devops_agent/validator.py`
- `engine/devops_agent/runtime.py`
- `engine/devops_agent/policies.py`
- `engine/devops_agent/evidence.py`
- `engine/devops_agent/cli.py`
- `engine/devops_agent/providers/__init__.py`
- `engine/devops_agent/providers/base.py`
- `engine/devops_agent/providers/gitea.py`
- `workflows/gitea-issue-delivery.md`
- `tests/unit/...`
- `tests/integration/...`
- `tests/fixtures/gitea/...`
- `tests/acceptance/test_gitea_acceptance.py`

Existing scripts will remain, but runtime may call them or share logic conceptually:

- `skills/gitea-issue-devops-agent/scripts/issue_audit.py`
- `skills/gitea-issue-devops-agent/scripts/change_scope.py`
- `skills/gitea-issue-devops-agent/scripts/preview_slot_allocator.py`

## Data Model

### Workflow Spec

Core fields:

- `name`
- `provider`
- `on`
- `permissions`
- `safe_outputs`
- `plan`
- `policy`
- `evidence`
- `body`

### Lock Artifact

Core fields:

- `version`
- `compiled_at`
- `source`
- `provider`
- `triggers`
- `policy`
- `safe_outputs`
- `required_evidence`
- `plan_defaults`
- `instructions`

### Run Artifact

Core fields:

- `run_id`
- `workflow_name`
- `provider`
- `event`
- `plan_state`
- `operations`
- `evidence`
- `result`

## Test Strategy

### Unit Tests

Verify:

- frontmatter parsing
- default normalization
- validator failures and successes
- policy enforcement
- provider request shaping

### Integration Tests

Verify:

- spec to lock compilation
- lock to runtime execution
- runtime interaction with a fake Gitea transport
- evidence persistence

### Acceptance Tests

Verify against a real Gitea repo using env vars:

- workflow compile and validate pass
- runtime can load a selected issue
- runtime can publish an evidence comment
- acceptance artifacts are produced locally

If env vars are absent, the acceptance suite must skip cleanly instead of failing misleadingly.

## Acceptance Criteria

This design is complete only when:

1. A repo-local Gitea workflow spec compiles into a lock artifact.
2. Invalid specs fail validation with clear messages.
3. Runtime enforces safe outputs and refuses undeclared writes.
4. Gitea real acceptance can read an issue and publish an evidence comment.
5. Automated unit and integration tests pass.
6. README and skill docs describe the new execution model and CLI usage.

## Rollout Notes

- Gitea is the first real provider.
- GitHub support is intentionally deferred, but the provider interface must be stable enough to add later.
- `jj` remains an internal reliability layer. This subsystem must not require `jj` for external usage.