Skip to content

Commit bd67d32

Browse files
OgeonX-AiAitomates
OgeonX-Ai
and
Aitomates
authored
docs(wiki): add docs-as-code wiki tree (Home, Architecture, Operations, Decisions) (#9)
- Documents demo-target role, trigger-to-PR architecture, verified CI/test commands - Indexes phase/quick-fix summaries and the ADR convention as the decisions trail - Adds codex:generate-image placeholder per docs/VISION.md house style Co-authored-by: Kim Harjamäki <kim.harjamaki@prosimo.fi>
1 parent ec62179 commit bd67d32

4 files changed

Lines changed: 147 additions & 0 deletions

File tree

‎docs/wiki/Architecture.md‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
# Architecture
2+
3+
`autopilot-demo` exists only to make the CAS autofix loop observable end to end. It is not the
4+
operator and not the worker host — it is a bounded-blast-radius target that produces a public,
5+
inspectable audit trail (failure event, queued issue, operator pickup, PR).
6+
7+
```mermaid
8+
flowchart LR
9+
A["Trigger Demo CI\n(workflow_dispatch)"] --> B["demo-ci.yml runs\n(ubuntu-latest)"]
10+
B --> C{CI result}
11+
C -->|failure| D["autopilot-create-issue.yml\ncreates intake issue"]
12+
D --> E["Issue: autofix + queued"]
13+
E --> F["autopilot-core operator\npicks up issue"]
14+
F --> G["Codex generates fix"]
15+
G --> H["Pull Request opened\nin this repo"]
16+
```
17+
18+
<!-- codex:generate-image prompt="A single glass test chamber on a factory floor with a red failure light, a robotic arm reaches in, tags the chamber with a queued ticket, then a second arm delivers a wrapped package labeled Pull Request; isometric, enterprise blue/graphite palette" style="isometric, enterprise, clean" replaces="mermaid-above" -->
19+
20+
## Repo boundary
21+
22+
- `autopilot-demo` is not the operator and not the worker host. It is the demonstration target.
23+
- `autopilot-core` owns queue scanning, Codex invocation, and PR creation.
24+
- `ci-autopilot` shows the worker/runtime implementation used to process queued repair tasks.
25+
26+
## Trust boundaries
27+
28+
- The demo's own CI (`ci.yml`) always passes — only `demo-ci.yml` is used to simulate a
29+
controlled failure signal, keeping normal push/PR checks green.
30+
- The intake path (`autopilot-create-issue.yml`) only creates issues; it never mutates code.
31+
- All repair mutation happens through a PR opened by `autopilot-core`, reviewed like any other
32+
change — no direct push to `main` from the automation path.
33+
34+
<!-- docs-verified: ec62179aa2c20bc731542de4ac3fec9cc94a831d 2026-07-08 -->

‎docs/wiki/Decisions.md‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
# Decisions
2+
3+
## Phase summaries (`.planning/phases/`)
4+
5+
| Phase | Topic |
6+
|---|---|
7+
| [01-enterprise-hardening](../../.planning/phases/01-enterprise-hardening/01-SUMMARY.md) | Enterprise hardening — CODEOWNERS, workflow permission tightening |
8+
9+
## Quick fixes (`.planning/quick/`)
10+
11+
| Entry | Topic |
12+
|---|---|
13+
| [260610-ppt-fix-pr-3-follow-up-readme-monitor-wordin](../../.planning/quick/260610-ppt-fix-pr-3-follow-up-readme-monitor-wordin/260610-ppt-SUMMARY.md) | README/monitor wording follow-up fix |
14+
15+
## Architecture Decision Records (`docs/adr/`)
16+
17+
[`docs/adr/`](../adr/README.md) is the formal ADR home for this repo (Context / Decision /
18+
Consequences, sequentially numbered). No ADR files have been recorded yet as of this writing —
19+
the directory holds only the governance README.
20+
21+
<!-- docs-verified: ec62179aa2c20bc731542de4ac3fec9cc94a831d 2026-07-08 -->

‎docs/wiki/Home.md‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
# autopilot-demo Wiki
2+
3+
`autopilot-demo` is the **proof repo** for the Coding-Autopilot-System autonomous CI-repair
4+
platform. It is a deliberately safe target that demonstrates the full failure-to-fix loop
5+
without touching production control-plane infrastructure.
6+
7+
## Role in the CAS portfolio
8+
9+
| Repo | Role |
10+
|---|---|
11+
| [autopilot-core](https://github.com/Coding-Autopilot-System/autopilot-core) | Control plane: queue scanning, Codex invocation, PR creation |
12+
| [ci-autopilot](https://github.com/Coding-Autopilot-System/ci-autopilot) | Worker/runtime reference implementation |
13+
| **autopilot-demo** (this repo) | Demonstration target: shows the failure-to-fix loop end to end |
14+
15+
## Quickstart
16+
17+
```bash
18+
# Trigger the Demo CI workflow (simulates a failure)
19+
gh workflow run demo-ci.yml -R Coding-Autopilot-System/autopilot-demo
20+
21+
# Watch for the intake issue to be created
22+
gh issue list -R Coding-Autopilot-System/autopilot-demo --label autofix --label queued
23+
24+
# Monitor autopilot-demo for the fix PR
25+
gh pr list -R Coding-Autopilot-System/autopilot-demo
26+
```
27+
28+
See the full [Demo runbook](../../README.md#demo-runbook) in the README for the reset and
29+
troubleshooting procedure.
30+
31+
## Where to go next
32+
33+
- [Architecture](Architecture.md) — the demo trigger-to-PR flow
34+
- [Operations](Operations.md) — verified run/test/CI commands
35+
- [Decisions](Decisions.md) — index of recorded architectural decisions
36+
37+
<!-- docs-verified: ec62179aa2c20bc731542de4ac3fec9cc94a831d 2026-07-08 -->

‎docs/wiki/Operations.md‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
# Operations
2+
3+
## Run the demo
4+
5+
```bash
6+
gh workflow run demo-ci.yml -R Coding-Autopilot-System/autopilot-demo
7+
gh issue list -R Coding-Autopilot-System/autopilot-demo --label autofix --label queued
8+
gh pr list -R Coding-Autopilot-System/autopilot-demo
9+
```
10+
11+
## Demo runbook
12+
13+
1. Trigger `.github/workflows/demo-ci.yml` with `simulate_failure=true` to produce a known
14+
failure signal. Regular pushes and default dispatches stay green.
15+
2. Confirm `.github/workflows/autopilot-create-issue.yml` creates an `autofix + queued` issue.
16+
3. Watch `autopilot-core` pick up the issue and open a PR back into this repo.
17+
4. Use this repo's issue, branch, and PR history as the audit trail for the demo.
18+
19+
## CI workflows
20+
21+
| Workflow | Purpose |
22+
|---|---|
23+
| `ci.yml` | Portfolio CI — YAML validation (always passes) |
24+
| `demo-ci.yml` | Demo trigger — simulates CI activity to test the intake flow |
25+
| `autopilot-create-issue.yml` | Intake — creates the `autofix + queued` issue on workflow failure |
26+
| `codeql.yml` | CodeQL static analysis |
27+
| `pr-lint.yml` | PR metadata/title linting |
28+
| `stale.yml` | Stale issue/PR sweep |
29+
| `pages.yml` | Publishes docs to GitHub Pages |
30+
31+
There is no coverage-percentage gate in this repo — `ci.yml` validates workflow YAML only, by
32+
design (this repo has no application code to test).
33+
34+
## Local verification
35+
36+
```bash
37+
python -m unittest discover -s tests -v
38+
```
39+
40+
Run this before triggering the demo if CI fails at the validation step, per the README's
41+
troubleshooting guidance.
42+
43+
## Reset and troubleshooting
44+
45+
1. Close the completed intake issue and merge or close its repair pull request before the next
46+
demonstration.
47+
2. Re-run with `simulate_failure=true`; intake reopens the matching issue when the same commit
48+
is demonstrated again.
49+
3. If no issue appears, inspect
50+
`gh run list -R Coding-Autopilot-System/autopilot-demo --workflow autopilot-create-issue.yml`
51+
and confirm the failed run was named `Demo CI`.
52+
4. If the issue remains queued, verify the `autopilot-core` operator is running and can read
53+
issues and create branches and pull requests in this repository.
54+
55+
<!-- docs-verified: ec62179aa2c20bc731542de4ac3fec9cc94a831d 2026-07-08 -->

0 commit comments

Comments
 (0)