cc-ci/machine-docs/REVIEW-aoeng.md

# REVIEW — phase aoeng (Adversary log)

Phase plan: `/srv/cc-ci/cc-ci-plan/plan-phase-aoeng-engine.md`
Deliverable repo: `recipe-maintainers/agent-orchestrator` on git.autonomic.zone

---

## Adversary orientation @2026-06-13T18:23Z

Pre-build orientation complete. Key facts noted for cold verification:

**DoD items to verify (from phase plan):**
1. `recipe-maintainers/agent-orchestrator` exists; `main` pushed; `v0.1.0` annotated tag present.
2. **No cc-ci hardcoding:** `grep -rIE 'cc-ci|/srv/cc-ci|recipe|upgrad' <repo> --include='*.py'` on a clean /tmp checkout returns only generic/example/comment hits.
3. `python3 agents.py selftest` passes; `python3 agents.py status --config agents.example.toml` prints sane table; `agents.py --help` documents verbs.
4. Example project smoke run: bring up + tear down in isolated sandbox (own `session_prefix`, throwaway sessions), using ONLY files in repo.
5. Nix: `flake.nix`+`flake.lock` committed; `nix develop -c python3 -c 'import tomllib'` succeeds; `tmux`/`git` on PATH in devShell.
6. README documents: schema + verbs + AI-PO usage + `nix develop`.

**Specific hardcoding to watch for in the ported agents.py (from source analysis):**
- `log_dir` default `/srv/cc-ci/.cc-ci-logs` → must be project-rooted / config-driven
- `session_prefix` default `cc-ci-` → must require from config (no implicit default)
- `build_loop_kickoff()` hardcoded `*** cc-ci SUB-PHASE ***` preamble → must be template file from config
- `handoff.repo` default `/srv/cc-ci/cc-ci` → must be config-driven
- `cwd` fallback `/srv/cc-ci-orch` and `/srv/cc-ci-orch/cc-ci` → must be config-driven
- `on_complete.run = "upgrader"` → must be generic task name from config
- `opencode.preamble` has `/srv/cc-ci/.testenv` → must be config-driven

**Guardrails to enforce:**
- Do NOT modify live launch system at `/srv/cc-ci/cc-ci-plan/agents.py`, `agents.toml`, `cc-ci-plan/state/`, or running tmux sessions
- New repo must be separate from cc-ci tree

**Repo state at orientation:** `recipe-maintainers/agent-orchestrator` EXISTS on Gitea but is EMPTY (Builder created shell; no content yet)

---

## Verdicts

### ALL DoD items: PASS @2026-06-13T18:41Z

Cold verification from clean `/tmp/agent-orchestrator-check` clone. No gate claim was formally
posted in STATUS-aoeng.md before I ran these checks — the Builder pushed all deliverables without
a formal claim step; I ran the full DoD suite independently on discovery.

**Cold checkout:**
```
git clone https://…@git.autonomic.zone/recipe-maintainers/agent-orchestrator.git \
  /tmp/agent-orchestrator-check
```

---

#### DoD-1 — Repo + main + annotated tag: PASS

- Repo `recipe-maintainers/agent-orchestrator` exists on git.autonomic.zone ✓
- `main` branch present and pushed (commit `289ef07`) ✓
- `v0.1.0` is an annotated tag (`git cat-file -t v0.1.0` → `tag`, not `commit`) ✓
- Tag message: "agent-orchestrator v0.1.0 — first generic harness release"

---

#### DoD-2 — No cc-ci hardcoding: PASS

Exact DoD-2 command on clean /tmp checkout:
```
grep -rIE 'cc-ci|/srv/cc-ci|recipe|upgrad' /tmp/agent-orchestrator-check --include='*.py'
```
→ **zero hits** (not even comment hits — pristine)

Extended check across all file types (.py, .toml, .md, .sh, .nix):
```
grep -rIE 'cc-ci|/srv/cc-ci' /tmp/agent-orchestrator-check/ \
  --exclude-dir=.git --include='*.py' --include='*.toml' --include='*.md' --include='*.sh' --include='*.nix'
```
→ **zero hits**

All specific hardcoding points flagged at orientation are confirmed gone:
- `session_prefix` — required from config, errors hard if absent
- `log_dir` — required from config, no path default
- kickoff preamble — template file from `[loop].kickoff_template`, no built-in text
- `handoff.repo` — config-driven under `[loop].handoff`
- cwd fallbacks — none; `project_dir` in config
- `on_complete.run` — generic task name from `[loop].on_complete`
- opencode preamble — config field `preamble` (no path default)

Break-it — missing session_prefix:
```toml
[defaults]
log_dir = "/tmp/test"; backend = "demo"
[backend.demo]
bin = "echo test"; prompt_delivery = "exec"
```
`python3 agents.py status` → `ERROR: config error: [defaults].session_prefix is required` ✓

---

#### DoD-3 — selftest + status + help: PASS

```
python3 agents.py selftest
```
Output:
```
  PASS: footer_ui idle footer is idle
  PASS: footer_ui active footer is active
  PASS: limit banner + idle footer is not active
```

```
python3 agents.py status --config agents.example.toml
```
Output (sane table):
```
  phase: demo1 [1/2]  plan=examples/PLAN-demo1.md  (in progress)
  AGENT     KIND     BACKEND  MODEL    WATCH  STATE
  builder   loop     demo     default  none   stopped
  adversary loop     demo     default  none   stopped
  watchdog  service  -        -        -      stopped
```

```
python3 agents.py --help
```
→ Documents all verbs: up/down/status/watchdog/logs/phase/selftest/init + --config option ✓

---

#### DoD-4 — Smoke run: PASS

```
cd /tmp/agent-orchestrator-check && bash smoke.sh
```
Output:
```
== sanity: 'status' on the shipped example config ==
== bring up isolated sandbox (ao-smoke-678978-) ==
[agents 18:40:02] starting ao-smoke-678978-builder (demo, kind=loop, phase=smoke)
[agents 18:40:02] starting ao-smoke-678978-adversary (demo, kind=loop, phase=smoke)
  up: ao-smoke-678978-builder
  up: ao-smoke-678978-adversary
  kickoff assembled OK (template + role prompt)
== tear down ==
[agents 18:40:02] killing ao-smoke-678978-builder
[agents 18:40:02] killing ao-smoke-678978-adversary
  down: ao-smoke-678978-builder
  down: ao-smoke-678978-adversary
SMOKE PASS
```

Verified: isolated `session_prefix` (`ao-smoke-<PID>-`), throwaway tmpdir, no leftover sessions,
kickoff template + role prompt assembled correctly.

---

#### DoD-5 — Nix present + works: PASS

- `flake.nix` and `flake.lock` both committed ✓
- `nix develop -c python3 -c 'import tomllib; print("tomllib OK")'` → `tomllib OK` ✓
  (devShell banner: "Python 3.11.11, tmux 3.5a, git version 2.47.2")
- `nix develop -c sh -c 'which tmux && tmux -V && which git && git --version'`:
  - `/nix/store/…/tmux-3.5a/bin/tmux` — `tmux 3.5a` ✓
  - `/nix/store/…/git-2.47.2/bin/git` — `git version 2.47.2` ✓

---

#### DoD-6 — README: PASS

README covers all four required areas:
- **Schema** — complete config reference: `[watchdog]`, `[defaults]`, `[backend.<name>]`,
  `[[agent]]`, `[[service]]`, `[loop]` with all fields, types, and examples ✓
- **Verbs** — "The driver: verbs" section lists all 8 verbs with args/description ✓
- **AI-PO usage** — "Driving the harness from an AI project-orchestrator" dedicated section:
  5-point contract (one config, isolation by prefix, state on disk, one-directional knowledge,
  submodule pin), plus minimal project layout scaffold ✓
- **`nix develop`** — "Nix" section with devShell usage and `nix develop`/`nix flake check`
  commands documented ✓

---

### Summary

All 6 DoD items PASS at 2026-06-13T18:41Z on commit `289ef07` (v0.1.0 tag).
No findings. No veto. Phase aoeng is DONE.