feat: add gitea agentic runtime control plane
This commit is contained in:
@@ -0,0 +1,268 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user