diff --git a/machine-docs/BACKLOG-porepo.md b/machine-docs/BACKLOG-porepo.md index eb363e9..7ef0c6e 100644 --- a/machine-docs/BACKLOG-porepo.md +++ b/machine-docs/BACKLOG-porepo.md @@ -3,14 +3,14 @@ ## Build backlog (Builder-owned — read-only to Adversary) -1. [in progress] Create `recipe-maintainers/project-orchestrator` repo (Gitea API) + clone to `/home/loops/porepo/`. -2. [ ] Add `engine/` submodule pinned at `agent-orchestrator` `v0.1.0`. -3. [ ] PO harness config: `agents.toml` (persistent `project-orchestrator` agent, fleet-mgmt role) + `prompts/`. -4. [ ] `fleet.toml` — documented schema + sample entry that parses. -5. [ ] Project-management capability: docs (`docs/`) + helper scripts (`scripts/`) for create / start-stop-update / list-status. -6. [ ] `flake.nix` + `flake.lock` devShell (python3>=3.11, tmux, git+submodule); README documents `nix develop`. -7. [ ] Bootstrap doc (how the first PO is hand-scaffolded). -8. [ ] Self-verify all DoD from a clean `/tmp` recursive clone inside `nix develop`; clean tree; claim gate. +1. [x] Create `recipe-maintainers/project-orchestrator` repo (Gitea API) + clone to `/home/loops/porepo/`. +2. [x] Add `engine/` submodule pinned at `agent-orchestrator` `v0.1.0` (289ef07). +3. [x] PO harness config: `agents.toml` (persistent `project-orchestrator` agent, fleet-mgmt role) + `prompts/`. +4. [x] `fleet.toml` — documented schema + sample entry that parses (`scripts/fleet.py validate`). +5. [x] Project-management capability: docs (`docs/`) + helper scripts (`scripts/`) for create / start-stop-update / list-status. +6. [x] `flake.nix` + `flake.lock` devShell (python3>=3.11, tmux, git+submodule); README documents `nix develop`. +7. [x] Bootstrap doc (`docs/bootstrap.md`). +8. [x] Self-verified all DoD from a clean anon `/tmp` recursive clone inside `nix develop`; clean tree; **gate CLAIMED** @ 346ed31. ## Adversary findings (none yet) diff --git a/machine-docs/JOURNAL-porepo.md b/machine-docs/JOURNAL-porepo.md index 4690ad6..02838ef 100644 --- a/machine-docs/JOURNAL-porepo.md +++ b/machine-docs/JOURNAL-porepo.md @@ -24,6 +24,38 @@ 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 add`s + 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 diff --git a/machine-docs/STATUS-porepo.md b/machine-docs/STATUS-porepo.md index 2c4b348..96e62ec 100644 --- a/machine-docs/STATUS-porepo.md +++ b/machine-docs/STATUS-porepo.md @@ -2,22 +2,88 @@ **Phase plan:** `/srv/cc-ci/cc-ci-plan/plan-phase-porepo-project-orchestrator.md` **Deliverable repo:** `recipe-maintainers/project-orchestrator` on `git.autonomic.zone` -**Builder working clone:** `/home/loops/porepo/project-orchestrator` (outside the cc-ci tracked tree) **Consumes harness:** `recipe-maintainers/agent-orchestrator` @ tag `v0.1.0` (commit `289ef07`) as `engine/` submodule --- -## Current state: IN PROGRESS — building +## Gate: porepo CLAIMED, awaiting Adversary -No gate claimed yet. (This STATUS file is Builder-owned and authoritative — `## DONE` will be -written here only after every DoD is Adversary-verified PASS in REVIEW-porepo.md.) +All 5 Definition-of-Done items are built, pushed, and self-verified from a clean **anonymous** +recursive `/tmp` clone inside `nix develop`. Working tree clean and pushed. Ready for cold +verification. + +### WHERE (verification inputs) +- Deliverable repo (public): `https://git.autonomic.zone/recipe-maintainers/project-orchestrator.git` +- `main` HEAD → `346ed31acbc0d98eeb2881a1b62998ac9544c002` (single feat commit) +- `engine/` submodule pin → `289ef07df40a8264f3a36b4e91b923d1424c4658` = tag `v0.1.0` of + `recipe-maintainers/agent-orchestrator` (also public; anon recursive clone needs no creds) +- `.gitmodules` URL is the **public** `https://git.autonomic.zone/recipe-maintainers/agent-orchestrator.git` + (no embedded creds) — so `git clone --recurse-submodules` works anonymously. +- File map: `agents.toml` (PO harness config), `prompts/{orchestrator,supervise}.md`, `fleet.toml` + (registry), `docs/{fleet-registry,manage-projects,bootstrap}.md`, `scripts/{fleet.py, + create-project.sh,start-project.sh,stop-project.sh,update-project.sh,_resolve.sh}`, + `flake.nix`+`flake.lock`, `README.md`, `.gitignore`. + +### HOW to cold-verify (fresh /tmp clone, anonymous, exactly as the plan specifies) +``` +cd /tmp && rm -rf porepo-cold +git clone --recurse-submodules https://git.autonomic.zone/recipe-maintainers/project-orchestrator.git porepo-cold +cd porepo-cold +git rev-parse HEAD # → 346ed31... +git submodule status # → 289ef07... engine (v0.1.0) + +# DoD-2: the PO's own config drives the harness +nix develop -c python3 engine/agents.py status + +# DoD-3: fleet registry schema + sample entry parse +nix develop -c python3 scripts/fleet.py validate +nix develop -c python3 scripts/fleet.py status + +# DoD-5: Nix devShell + tomllib + bootstrap doc +nix develop -c python3 -c 'import tomllib' +test -f docs/bootstrap.md && echo "bootstrap doc present" + +# DoD-4: create-a-project flow demonstrated → valid standalone project, no PO/fleet metadata +nix develop -c bash scripts/create-project.sh scratch-verify --dir /tmp/po-scratch --ref v0.1.0 +nix develop -c bash -c 'cd /tmp/po-scratch/scratch-verify && python3 engine/agents.py status' +( cd /tmp/po-scratch/scratch-verify && git submodule status ) # engine pinned @ v0.1.0 +( cd /tmp/po-scratch/scratch-verify \ + && grep -ril -e 'fleet' -e 'project-orchestrator' -e 'project orchestrator' . \ + --exclude-dir=engine --exclude-dir=.git \ + && echo "BAD: PO/fleet metadata found" || echo "clean: no PO/fleet metadata" ) +# cleanup (throwaway; never registered, never touched live cc-ci): +rm -rf /tmp/po-scratch /tmp/porepo-cold +``` + +### EXPECTED outcomes (from my cold anon run @2026-06-13T19:20Z on 346ed31, /tmp clone, nix develop) +- **Clone:** `git rev-parse HEAD` = `346ed31...`; `git submodule status` = + ` 289ef07df40a8264f3a36b4e91b923d1424c4658 engine (v0.1.0)`; `engine/agents.py` present (proves + the recursive submodule fetch worked anonymously). devShell banner: `Python 3.11.11, tmux 3.5a, + git version 2.47.2`. +- **DoD-1 (repo+submodule+main):** repo exists & public; `main` pushed at `346ed31`; `engine/` + pinned at `v0.1.0` (`289ef07`). +- **DoD-2 (status):** `engine/agents.py status` prints a table listing the `project-orchestrator` + persistent agent (backend claude, model claude-opus-4-8, watch heal, STATE stopped) and the + watchdog service — no error, rc=0. +- **DoD-3 (fleet.toml):** `fleet.py validate` → `fleet: OK — 1 project(s), schema v1`, rc=0; + `fleet.py status` lists the sample `example-recipe-ci` entry (enabled, agent-orchestrator@v0.1.0) + + `total=1 enabled=1 disabled=0`. Schema documented in `docs/fleet-registry.md`. +- **DoD-4 (create flow):** `create-project.sh` scaffolds `/tmp/po-scratch/scratch-verify` with an + `engine/` submodule pinned at `289ef07` (v0.1.0) and an `init`-scaffolded `agents.toml`; + `engine/agents.py status` in it prints its agent table (rc=0); tracked files are exactly + `.gitignore .gitmodules agents.toml` (no PO/fleet files); the grep prints + `clean: no PO/fleet metadata`. Flow documented in `docs/manage-projects.md`. +- **DoD-5 (Nix+bootstrap):** `python3 -c 'import tomllib'` prints nothing & rc=0 inside the + devShell; `docs/bootstrap.md` present. + +(Reasoning / design rationale is in JOURNAL-porepo.md, not here, to preserve anti-anchoring.) ## Gate status | DoD item | Status | |---|---| -| D1 repo exists + main pushed + engine/ submodule pinned @ v0.1.0 | TODO | -| D2 clean recursive /tmp clone: `nix develop -c python3 engine/agents.py status` works | TODO | -| D3 fleet.toml schema present + documented; sample entry parses | TODO | -| D4 create-a-project flow documented AND demonstrated (scratch project valid, no PO/fleet metadata, its status works) | TODO | -| D5 Nix works (`nix develop -c python3 -c 'import tomllib'`); bootstrap doc present | TODO | +| D1 repo exists + main pushed + engine/ submodule pinned @ v0.1.0 | CLAIMED | +| D2 clean recursive /tmp clone: `nix develop -c python3 engine/agents.py status` works | CLAIMED | +| D3 fleet.toml schema present + documented; sample entry parses | CLAIMED | +| D4 create-a-project flow documented AND demonstrated (scratch valid, no PO/fleet metadata, status works) | CLAIMED | +| D5 Nix works (`nix develop -c python3 -c 'import tomllib'`); bootstrap doc present | CLAIMED |