diff --git a/docs/wiki/Architecture.md b/docs/wiki/Architecture.md new file mode 100644 index 0000000..c5ace24 --- /dev/null +++ b/docs/wiki/Architecture.md @@ -0,0 +1,40 @@ +# Architecture + +`autopilot-core` implements the intake-governance and operator-scheduling half of the CAS +autofix loop. It never touches target-repo code directly — it schedules the Codex-driven fix +generation and lets a pull request carry the change through normal review. + +```mermaid +flowchart LR + A[CI Failure in\nopted-in repo] --> B[autopilot-create-issue.yml] + B --> C[Issue: autofix + queued] + C --> D[autopilot-operator.yml\nself-hosted Windows runner] + D --> E[Codex fix generation] + E --> F[Pull Request opened\nin target repo] + F --> G[Auto-merge / human review] + H[autopilot-org-installer.yml\nhourly scan] -.installs intake into.-> B +``` + + + +## Components + +| Component | Trigger | Purpose | +|---|---|---| +| `autopilot-create-issue.yml` | `workflow_run` failure | Creates the intake issue labeled `autofix + queued` | +| `autopilot-operator.yml` | schedule + `workflow_dispatch` | Scans issues, invokes Codex, opens PRs | +| `autopilot-org-installer.yml` | hourly + dispatch | Installs the intake workflow into repos that opt in via `.autopilot/opt-in` | +| `autopilot-docs-daily.yml` | daily | Refreshes the dashboard status page | + +## Trust boundaries + +- The operator only acts on issues labeled `autofix + queued` and skips `risky` or + `needs-design` labels. +- Diffs are minimal by design — no secrets, no destructive operations — and required + verification runs before a PR is opened. +- The operator requires the `ORG_AUTOPILOT_TOKEN` secret, scoped least-privilege for + cross-repo mutation; it runs on a self-hosted Windows runner, not GitHub-hosted compute. +- This repo does not provision or deploy any cloud infrastructure; it is GitHub Actions + orchestration plus a locally-hosted runner. + + diff --git a/docs/wiki/Decisions.md b/docs/wiki/Decisions.md new file mode 100644 index 0000000..a6e2a35 --- /dev/null +++ b/docs/wiki/Decisions.md @@ -0,0 +1,20 @@ +# Decisions + +This repo tracks two decision trails: + +## Phase summaries (`.planning/phases/`) + +| Phase | Topic | +|---|---| +| [01-enterprise-audit](../../.planning/phases/01-enterprise-audit/) | Enterprise hardening audit — CODEOWNERS, workflow permission tightening, operator timeout coverage, Pester unit-test extension (see commit `cd76345`) | + +## Architecture Decision Records (`docs/adr/`) + +The [`docs/adr/`](../adr/README.md) directory is the formal ADR home for this repo, governed by +the rule that any major technical decision or new dependency must be recorded there (Context / +Decision / Consequences, sequentially numbered). No ADR files have been recorded yet as of this +writing — the directory currently holds only the governance README describing the convention. +Future architectural decisions (e.g., changes to the intake/operator contract) should land there +and be indexed on this page. + + diff --git a/docs/wiki/Home.md b/docs/wiki/Home.md new file mode 100644 index 0000000..26408bd --- /dev/null +++ b/docs/wiki/Home.md @@ -0,0 +1,33 @@ +# autopilot-core Wiki + +`autopilot-core` is the **control plane** of the Coding-Autopilot-System autonomous CI-repair +platform. It owns org-wide intake governance, operator scheduling, PR creation, and rollout +visibility for the autofix loop. + +## Role in the CAS portfolio + +CAS ships three cooperating repos for CI self-repair: + +| Repo | Role | +|---|---| +| **autopilot-core** (this repo) | Control plane: org-wide intake governance, operator scheduling, PR creation | +| [ci-autopilot](https://github.com/Coding-Autopilot-System/ci-autopilot) | Worker/runtime: self-hosted-runner agent that inventories the issue queue | +| [autopilot-demo](https://github.com/Coding-Autopilot-System/autopilot-demo) | Proof repo: safe target demonstrating the full failure-to-fix loop | + +## Quickstart + +1. Set the org variable `ORG` in GitHub Actions for this repo. +2. Configure the least-privilege `ORG_AUTOPILOT_TOKEN` secret for opted-in repository mutations. +3. Install `autopilot-create-issue.yml` into target repos, or use `autopilot-org-installer.yml`. +4. Ensure a self-hosted Windows runner with Codex and `OPENAI_API_KEY` is online. +5. Trigger `autopilot-operator.yml` manually to validate the setup. + +Full detail: [README Quick start](../../README.md#quick-start). + +## Where to go next + +- [Architecture](Architecture.md) — the intake-to-PR flow and its trust boundaries +- [Operations](Operations.md) — verified run/test/CI commands +- [Decisions](Decisions.md) — index of recorded architectural decisions + + diff --git a/docs/wiki/Operations.md b/docs/wiki/Operations.md new file mode 100644 index 0000000..2970487 --- /dev/null +++ b/docs/wiki/Operations.md @@ -0,0 +1,53 @@ +# Operations + +## Run the test suite + +```powershell +pwsh ./tests/run-tests.ps1 +``` + +This runs workflow YAML validation, control-plane contract tests, and Pester 5 unit tests in +one command — the same entry point CI uses. + +## CI gate (`.github/workflows/ci.yml`) + +CI runs on `ubuntu-latest` for every push/PR to `main` and performs, in order: + +1. `python tests/validate_workflows.py` — validates workflow YAML. +2. `./tests/contract-tests.ps1` — validates control-plane contracts. +3. Pester 5.5.0+ unit tests over `./tests` with `Invoke-Pester` (`Run.Exit = $true`, + `Output.Verbosity = 'Detailed'`). + +Pester coverage focuses on the safety- and payload-critical logic: `Assert-SafeChangeSet` +(sensitive-path and diff-budget guards), `Get-ChangedFile` (porcelain parsing), `Search-Issue` +(GraphQL request construction), and the `Autopilot.Common` helpers (`Get-RepoName`, +`Invoke-GhJson`, `Get-LogTail`). + +There is no branch-coverage percentage gate in this repo's CI as of this writing — the gate is +pass/fail on the validation, contract, and Pester steps, not a coverage threshold. + +## Other CI workflows + +| Workflow | Trigger | Purpose | +|---|---|---| +| `codeql.yml` | scheduled + push | CodeQL static analysis | +| `pr-lint.yml` | PR | PR metadata/title linting | +| `stale.yml` | scheduled | Stale issue/PR sweep | +| `pages.yml` | push to `main` | Publishes the dashboard to GitHub Pages | + +## Manual dispatch + +Trigger the operator manually to validate a setup change: + +```bash +gh workflow run autopilot-operator.yml -R Coding-Autopilot-System/autopilot-core +``` + +## Runbooks + +- [docs/status.md](../status.md) — status snapshot +- [docs/runbooks/operator.md](../runbooks/operator.md) — operator runbook +- [docs/runbooks/install-to-repo.md](../runbooks/install-to-repo.md) — repo onboarding runbook +- [docs/demos/demo-repo.md](../demos/demo-repo.md) — demo walkthrough using `autopilot-demo` + +