cc-ci/machine-docs/JOURNAL-porepo.md

JOURNAL — phase porepo (Builder)

2026-06-13T19:05Z — Bootstrap / orientation

Read the phase plan, plan-agent-orchestrator.md, and the harness README at /home/loops/aoeng/agent-orchestrator/README.md. Key facts established:

• Harness agent-orchestrator is built + tagged v0.1.0 (tag object a89d30f → commit 289ef07). Working clone: /home/loops/aoeng/agent-orchestrator. Repo is public on Gitea (private:false), so a fresh git clone --recurse-submodules fetches engine/ without creds.
• engine/agents.py status only needs a valid agents.toml (it reads config, prints a table; does not require running sessions or live backends). So a PO config with one persistent project-orchestrator agent will pass status.
• Config schema (README): [watchdog], [backend.<name>], [defaults] (session_prefix + log_dir REQUIRED), [[agent]]/[[service]], [loop]. project_dir resolves relative paths.
• One-directional knowledge: the PO repo holds the fleet registry (fleet.toml); a project repo holds NO PO/fleet metadata — engine submodule pin + PO's fleet.toml are the only record of project↔harness↔ref.

Decision: pin engine/ at the commit the v0.1.0 tag points to (289ef07), per DoD wording "pinned to agent-orchestrator v0.1.0". The tests commit cdcece9 is after the tag and is not required.

Gitea API reachable with bot creds (200); recipe-maintainers/project-orchestrator does not yet exist (404); org recipe-maintainers exists (id 65).

2026-06-13T19:20Z — Built + cold-verified, claiming gate

Built the whole PO repo in /home/loops/porepo/project-orchestrator, pushed main at 346ed31.

Design choices (the WHY behind STATUS facts):

• PO agent is a single persistent fleet-management agent, not a [loop] pair — the plan says "a persistent project-orchestrator agent is enough to start; add a loop only if useful." A loop's phase machine models a build-to-DoD sequence, which fleet management is not. So no [loop] block; status simply prints the agents table (no phase line). Hourly wake → prompts/supervise.md gives it a periodic read-only fleet sweep.
• fleet.toml uses [[project]] array-of-tables with required name/location/harness/ref/ enabled/secrets + optional config/notes. scripts/fleet.py validates (rejects unknown fields and dup names — a typo guard) and reports. The registry is the only project↔harness↔ref record; the in-project engine/ submodule pin is the in-repo half (a plain git fact, no fleet semantics).
• create-project.sh deliberately keeps the project ignorant of the PO: it git submodule adds the harness, checks out the ref, then scaffolds config with the harness's own agents.py init (harness-only config), stamps a unique session_prefix, and commits. Registering in fleet.toml is a separate, opt-in --register step that writes only to the PO side. The scratch project's tracked files are exactly .gitignore .gitmodules agents.toml — zero PO/fleet metadata.
• Nix flake reuses the engine's nixpkgs pin (50ab7937…, lastModified 1751274312) so the devShell is identical/known-good (python311 + tmux + git). flake.lock written by hand to match.
• Pinned engine at the v0.1.0 commit 289ef07 (the tag points there); the later cdcece9 tests commit is intentionally not pinned (DoD says v0.1.0).

Verification (full command+output transcript): ran every DoD check from a fresh anonymous recursive /tmp clone inside nix develop (Python 3.11.11, tmux 3.5a, git 2.47.2). All passed: recursive submodule fetch worked with no creds; agents.py status listed the PO agent; fleet.py validate → OK — 1 project(s), schema v1; import tomllib rc=0; create-project.sh produced a valid standalone scratch project (engine @ v0.1.0, status rc=0, grep → clean: no PO/fleet metadata). Cleaned up all /tmp scratch artifacts. Exact commands + expected outputs mirrored into STATUS-porepo.md for the Adversary.

File-ownership coordination note

The Adversary had pre-created STATUS-porepo.md / JOURNAL-porepo.md as placeholders before I started. Per protocol §6.1 these are Builder-owned (STATUS is the authoritative ## DONE handshake file the Adversary verifies against; JOURNAL is my reasoning). I took them over and left REVIEW-porepo.md + the ## Adversary findings section of BACKLOG-porepo.md to the Adversary. Sent an ADVERSARY-INBOX.md heads-up so it keeps its tracking in REVIEW.