Coding-Autopilot-System · OgeonX-Ai · Jul 8, 2026 · Jul 8, 2026
diff --git a/docs/wiki/Architecture.md 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"]
+```
+
+<!-- codex:generate-image prompt="A lighthouse keeper's watch room with a self-hosted Windows terminal scanning a harbor of docked ships each labeled with a GitHub issue number, the keeper logs a read-only inventory ledger, a dashed line to a locked gate labeled future guarded dispatcher; isometric, enterprise blue/graphite palette" style="isometric, enterprise, clean" replaces="mermaid-above" -->
+
+## 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.
+
+<!-- docs-verified: 4590462b38e0a835385c3a7c4a4b35d761bed5dc 2026-07-08 -->
diff --git a/docs/wiki/Decisions.md 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.
+
+<!-- docs-verified: 4590462b38e0a835385c3a7c4a4b35d761bed5dc 2026-07-08 -->
diff --git a/docs/wiki/Home.md 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
+
+<!-- docs-verified: 4590462b38e0a835385c3a7c4a4b35d761bed5dc 2026-07-08 -->
diff --git a/docs/wiki/Operations.md 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.
+
+<!-- docs-verified: 4590462b38e0a835385c3a7c4a4b35d761bed5dc 2026-07-08 -->