diff --git a/docs/wiki/Architecture.md b/docs/wiki/Architecture.md new file mode 100644 index 0000000..a206c3c --- /dev/null +++ b/docs/wiki/Architecture.md @@ -0,0 +1,42 @@ +# Architecture + +`ci-autopilot` packages the worker/runtime side of the platform. The runtime surface is +deliberately small: `agent/poll_once.py` is a Python 3.12 stdlib-only program (no external +dependencies) that runs on a self-hosted Windows runner via the `fixer.yml` workflow, polling +the issue queue and listing queued repair tasks for operator visibility. + +```mermaid +flowchart LR + A["GitHub Actions failure\ndetected"] --> B["autopilot-failure-intake.yml\n(intake workflow)"] + B --> C["Issue queue\n(runner-offline label)"] + C --> D["agent/poll_once.py\n(Python 3.12, self-hosted Windows runner)"] + D --> E["Operator visibility\n(read-only inventory)"] + E -. "future guarded dispatcher" .-> F["PR-only repair path"] +``` + + + +## Core components + +- **autopilot-failure-intake.yml** — intake workflow triggered on `workflow_run` failure + events; creates a queued issue. +- **autopilot-create-issue.yml** — creates GitHub issues via `actions/github-script` when + monitored workflows fail. +- **fixer.yml** — runs the read-only `agent/poll_once.py` queue inventory on the self-hosted + Windows runner. +- **agent/poll_once.py** — Python 3.12 stdlib agent; validates repository input and inventories + the issue queue. +- **runner-smoke-test.yml** / **runner-health.yml** — smoke-test and scheduled health check for + the self-hosted runner. + +## Trust boundaries + +- Clear separation of concerns: issue intake and governance stay in `autopilot-core`; worker + execution and any future guarded repair dispatch stay on this repo's worker boundary. +- The agent is intentionally read-only today — it does not execute issue content, mutate + repositories, or dispatch Codex. Guarded autonomous repair dispatch is tracked as an open + finding (see [Decisions](Decisions.md)), not shipped functionality. +- The self-hosted runner model supports enterprise network boundaries and least-privilege token + handling; this repo provisions no cloud infrastructure. + + diff --git a/docs/wiki/Decisions.md b/docs/wiki/Decisions.md new file mode 100644 index 0000000..49ec4a6 --- /dev/null +++ b/docs/wiki/Decisions.md @@ -0,0 +1,27 @@ +# Decisions + +## 2026-06-10 enterprise audit-fix (`.planning/audits/20260610-ci-autopilot-audit-fix.md`) + +A `gsd-audit-fix` pass (severity `all`, max 8 auto-fixes) covering worker/runtime correctness, +security boundaries, CI, tests, packaging, reliability, and documentation. Key outcomes: + +| ID | Finding | Result | +|---|---|---| +| F-01 | Persistent self-hosted checkout retained prior-job files | Fixed | +| F-02 | External GitHub Actions used mutable tags | Fixed; pinned to immutable commits | +| F-03 | Worker accepted malformed repo/API inputs, no boundary tests | Fixed; validation + tests added | +| F-08 | Docs claimed autonomous dispatch not present in implementation | Fixed; read-only contract documented | +| F-11 | Guarded autonomous repair dispatcher and queue state machine are absent | Open (manual-only) — this is why the agent is read-only today | +| F-12 | Persistent runner host hardening/isolation not implemented as code | Open (manual-only) — requires a deployment architecture decision | + +The full finding list, including items not yet attempted (F-09, F-13, F-15, F-16), is in the +[audit report](../../.planning/audits/20260610-ci-autopilot-audit-fix.md). + +## Architecture Decision Records (`docs/adr/`) + +[`docs/adr/`](../adr/README.md) is the formal ADR home for this repo. No sequentially-numbered +ADR files have been recorded yet as of this writing — the directory holds only the governance +README. The audit findings above (F-11, F-12 in particular) are the leading candidates for the +first formal ADRs once a guarded-dispatch design is chosen. + + diff --git a/docs/wiki/Home.md b/docs/wiki/Home.md new file mode 100644 index 0000000..a9e0732 --- /dev/null +++ b/docs/wiki/Home.md @@ -0,0 +1,34 @@ +# ci-autopilot Wiki + +`ci-autopilot` is the **worker/runtime** side of the CAS autonomous CI-repair platform. It +monitors GitHub Actions workflows, detects failures, and exposes them through an issue queue via +a self-hosted-runner-hosted Python agent. The current agent is deliberately read-only: it +inventories queued issues; autonomous repair dispatch and queue state transitions are not +implemented yet. + +## Role in the CAS portfolio + +| Repo | Role | +|---|---| +| [autopilot-core](https://github.com/Coding-Autopilot-System/autopilot-core) | Control plane for org-level scheduling, rollout, and PR governance | +| **ci-autopilot** (this repo) | Worker/runtime implementation for runner execution and read-only queue polling | +| [autopilot-demo](https://github.com/Coding-Autopilot-System/autopilot-demo) | Demonstration target used to show the runtime and control plane working together | + +## Quickstart + +```pwsh +# Prerequisites: Python 3.12 and authenticated GitHub CLI +$env:GH_TOKEN = gh auth token +python -m agent.poll_once +``` + +The worker only reads and lists queued issues. It does not execute issue content, mutate +repositories, or dispatch Codex. + +## Where to go next + +- [Architecture](Architecture.md) — the self-hosted runner + fixer/poll loop +- [Operations](Operations.md) — verified run/test/CI commands +- [Decisions](Decisions.md) — index of recorded architectural decisions and the 2026-06-10 audit + + diff --git a/docs/wiki/Operations.md b/docs/wiki/Operations.md new file mode 100644 index 0000000..e98c316 --- /dev/null +++ b/docs/wiki/Operations.md @@ -0,0 +1,65 @@ +# Operations + +## CI gate (`.github/workflows/ci.yml`) + +CI runs on `ubuntu-latest` for every push/PR to `main`: + +```bash +python -m py_compile agent/poll_once.py +python -c "import agent.poll_once" +python -m unittest discover -v +``` + +There is no `--cov-fail-under` or branch-coverage percentage gate configured in `ci.yml` as of +this writing — the CI gate is syntax check, import check, and unit-test pass/fail, not a +coverage threshold. + +## Local run + +```pwsh +# Prerequisites: Python 3.12 and authenticated GitHub CLI +$env:GH_TOKEN = gh auth token +python -m agent.poll_once +``` + +## Runner service control + +```pwsh +cd C:\actions-runner +$serviceName = Get-Content .\.service +Get-Service -Name $serviceName +Start-Service -Name $serviceName +Stop-Service -Name $serviceName +Restart-Service -Name $serviceName +``` + +## Runner health + +- `Runner Health Monitor` runs every 15 minutes on GitHub-hosted runners; if the self-hosted + runner is offline it opens or updates an issue labeled `runner-offline`, and sends an email + alert if `SMTP_*`/`EMAIL_*` secrets are configured. +- If the health monitor cannot list runners with the default `GITHUB_TOKEN`, add a repo secret + `RUNNER_PAT` with `repo` and `workflow` scopes (plus `read:org` for org repos). + +## Other CI workflows + +| Workflow | Purpose | +|---|---| +| `autopilot-failure-intake.yml` | Intake on `workflow_run` failure | +| `autopilot-create-issue.yml` | Issue creation via `actions/github-script` | +| `fixer.yml` | Runs the read-only queue-inventory agent on the self-hosted runner | +| `runner-smoke-test.yml` | On-demand runner smoke test | +| `runner-health.yml` | Scheduled + on-demand runner health check | +| `codeql.yml` | CodeQL static analysis | +| `pr-lint.yml` | PR metadata/title linting | +| `stale.yml` | Stale issue/PR sweep | +| `pages.yml` | Publishes docs to GitHub Pages | + +## Runbook path + +1. [docs/control-plane.md](../control-plane.md) — issue-queue contract with `autopilot-core`. +2. [docs/runner-setup.md](../runner-setup.md) — provision the worker host. +3. [docs/operations.md](../operations.md) and [docs/troubleshooting.md](../troubleshooting.md) — + day-2 support. + +