rewrite phase 1
This commit is contained in:
@@ -0,0 +1,132 @@
|
||||
# Agent CI repository instructions
|
||||
|
||||
## Scope
|
||||
|
||||
- These instructions apply to the whole repository. A nested `AGENTS.md` adds or overrides
|
||||
instructions for its subtree; `opencode/AGENTS.md` contains runtime-specific guidance.
|
||||
- Agent CI is a private Gitea webhook service that turns issue and pull-request comments into
|
||||
durable OpenCode workflows. Read `README.md` before changing command behavior, persistence,
|
||||
recovery, deployment, or the security boundary.
|
||||
- Keep changes focused. Preserve unrelated work in a dirty worktree and do not rewrite code outside
|
||||
the requested change merely for consistency.
|
||||
|
||||
## Repository map
|
||||
|
||||
- `src/agentci/engine/`: immutable domain models and events, the pure reducer, SQLite persistence,
|
||||
task claiming, and the `JobRun` event interface.
|
||||
- `src/agentci/worker.py`: durable control/job queues, authorization, execution, recovery, and
|
||||
comment reconciliation.
|
||||
- `src/agentci/workflows/`: planning, implementation, review, and pull-request orchestration.
|
||||
- `src/agentci/{gitea,git,opencode,codegraph,development}.py`: external-effect boundaries.
|
||||
- `src/agentci/{app,runtime,config,webhook,health}.py`: application lifecycle, configuration, and
|
||||
HTTP entry points.
|
||||
- `src/agentci/prompts/` and `src/agentci/prompts/schemas/`: model prompts and structured-output
|
||||
contracts; keep these concerns outside Python orchestration.
|
||||
- `src/agentci/migrations/`: ordered SQLite migrations.
|
||||
- `tests/`: pytest suite, generally organized by module or behavior.
|
||||
- `compose.yaml`, `Dockerfile`, `scripts/`, `install-scripts/`, and `opencode/`: deployment and
|
||||
trusted runtime configuration.
|
||||
|
||||
## Setup and commands
|
||||
|
||||
Use Python 3.13 or newer and `uv`. Run commands from the repository root.
|
||||
|
||||
```sh
|
||||
uv sync
|
||||
```
|
||||
|
||||
Run the narrowest relevant test while iterating:
|
||||
|
||||
```sh
|
||||
uv run pytest tests/test_<area>.py
|
||||
uv run pytest tests/test_<area>.py::test_<behavior>
|
||||
uv run pytest -k '<expression>'
|
||||
```
|
||||
|
||||
Run the standard Python checks before completion:
|
||||
|
||||
```sh
|
||||
uv run ruff check .
|
||||
uv run pyright
|
||||
uv run pytest
|
||||
```
|
||||
|
||||
Coverage is diagnostic and has no required threshold:
|
||||
|
||||
```sh
|
||||
uv run pytest --cov=agentci --cov-branch
|
||||
```
|
||||
|
||||
For deployment-related changes, also run:
|
||||
|
||||
```sh
|
||||
docker compose config
|
||||
```
|
||||
|
||||
Run `docker compose build` when changing dependencies, the image, runtime scripts, installers, or
|
||||
OpenCode configuration. It may require network access and takes longer than the normal checks.
|
||||
|
||||
## Engineering conventions
|
||||
|
||||
- Target Python 3.13, keep lines at or below 100 characters, and follow the Ruff and Pyright settings
|
||||
in `pyproject.toml`. Use type annotations and existing modern Python patterns.
|
||||
- Keep jobs and workflows immutable. Domain snapshots use frozen dataclasses; create updated values
|
||||
rather than mutating state in place.
|
||||
- Keep `engine/reducer.py` pure: no I/O, clocks, logging, or external calls. Express state changes as
|
||||
events and task requests.
|
||||
- Apply state transitions, event persistence, and resulting task creation atomically through
|
||||
`Repository`. The `jobs` table is the authoritative snapshot; timestamps are storage metadata.
|
||||
- Keep side effects in the worker, workflows, or top-level integration modules. Pass workflow
|
||||
dependencies explicitly through `WorkflowServices` and progress through `JobRun`.
|
||||
- Preserve webhook/event idempotency, per-target FIFO execution, bounded unrelated concurrency, and
|
||||
deterministic comment reconciliation.
|
||||
- Preserve restart semantics: queued work may resume, but an active partially executed model turn is
|
||||
failed and its sessions are aborted rather than replayed.
|
||||
- Use structured logging fields such as `operation`, `job_id`, `stage`, and task identifiers. Never
|
||||
log credentials, secret contents, authorization headers, or private prompt data.
|
||||
- Add a new numbered migration for schema changes. Never edit a migration that may already have been
|
||||
applied.
|
||||
- Keep prompts and JSON schemas synchronized. Add or update tests when changing either contract.
|
||||
- Declare dependencies in `pyproject.toml` and let `uv` update `uv.lock`; do not edit the lockfile by
|
||||
hand.
|
||||
|
||||
## Testing conventions
|
||||
|
||||
- Add regression tests for behavior changes, especially reducer transitions, persistence and
|
||||
idempotency, restart recovery, queue ordering, webhook security, and integration error handling.
|
||||
- Prefer behavior-oriented test names, table-driven `pytest.mark.parametrize` cases, `tmp_path` for
|
||||
filesystem/database isolation, and fake clients or `httpx.MockTransport` for external services.
|
||||
- Async tests run with `asyncio_mode = "auto"`; do not add an asyncio marker solely to make a test
|
||||
asynchronous.
|
||||
- Assert externally meaningful state, emitted events/tasks, ordering, rendered comments, and safe
|
||||
error text rather than private implementation details.
|
||||
- Do not make the default unit suite depend on live Gitea, OpenCode, provider credentials, Docker,
|
||||
or network access.
|
||||
|
||||
## Security and operational boundaries
|
||||
|
||||
- Never commit or expose `.env`, `secrets/`, tokens, passwords, provider credentials, runtime
|
||||
databases, cloned private repositories, or Docker volume contents. Do not send secrets or private
|
||||
repository content to external search or research services.
|
||||
- Preserve webhook HMAC verification, bot-comment filtering, requester write-permission checks, and
|
||||
secret-file loading.
|
||||
- OpenCode is not an OS sandbox. Do not weaken its permissions, enable repository-local configuration
|
||||
or external skills, expose its server to the host, add privileged/capability settings, or add
|
||||
writable host mounts without an explicit security review.
|
||||
- `install-scripts/` is trusted operator code. Keep scripts idempotent, path-safe, and compatible with
|
||||
the sanitized environment documented in `install-scripts/README.md`; never pass Agent CI or Gitea
|
||||
credentials to them.
|
||||
- Git pushes performed by Agent CI must remain non-forcing.
|
||||
- Do not run provider authentication, start/restart deployment services, modify production data, or
|
||||
perform other live operations unless the user explicitly requests it.
|
||||
- Do not edit or commit generated/local state in `.venv/`, `.pytest_cache/`, `.ruff_cache/`,
|
||||
`.codegraph/`, `__pycache__/`, `dist/`, `data/`, or `secrets/`.
|
||||
|
||||
## Completion expectations
|
||||
|
||||
- Run focused tests first, then all applicable standard checks. If a check cannot run, report the
|
||||
exact command and reason.
|
||||
- Update `README.md`, `.env.example`, and relevant operational documentation when changing commands,
|
||||
configuration, deployment, recovery behavior, or security assumptions.
|
||||
- Summarize behavior changes, validation performed, and any migration, compatibility, or security
|
||||
implications in the final response or pull-request description.
|
||||
Reference in New Issue
Block a user