From e144354668a3f74a3e814868867900b2399b176f Mon Sep 17 00:00:00 2001 From: autonomic-bot Date: Thu, 11 Jun 2026 20:56:24 +0000 Subject: [PATCH] loops: mandate machine-docs/ for ALL coordination files (kickoff/prompts/plan/AGENTS) Recent phases wrote STATUS/BACKLOG/REVIEW/JOURNAL to the repo ROOT because build_kickoff + plan.md's tree used bare filenames, even though the loops' AGENTS.md + INBOX/DECISIONS/DEFERRED conventions already said machine-docs/. Make machine-docs/ the single mandated home everywhere: build_kickoff now emits machine-docs/ paths + an explicit FILE-LOCATION RULE; both loop prompts and plan.md (tree + seed step) updated; orchestrator AGENTS.md documents + enforces it. resolve_state/INBOX handoff already read machine-docs/ first. --- AGENTS.md | 10 ++++++++++ cc-ci-plan/launch.py | 19 +++++++++++++------ cc-ci-plan/plan.md | 10 +++++++--- cc-ci-plan/prompts/adversary.md | 1 + cc-ci-plan/prompts/builder.md | 1 + 5 files changed, 32 insertions(+), 9 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 4307835..c5d0f0b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -62,6 +62,16 @@ Use it to: tail loop logs (`cc-ci-plan/launch.sh logs builder|adversary|watchdog power-cycle/recreate the cc-ci VM (see `cc-ci-plan/kickoff.md` → "Fallback: restart/recreate the cc-ci VM"). The orchestrator is the human's steering wheel; the loops are the engine. +## Loop file-location rule (machine-docs/) + +In the **cc-ci loops repo**, ALL coordination / loop-state files live under `machine-docs/`, NEVER +the repo root: phase-namespaced `STATUS-*.md` / `BACKLOG-*.md` / `REVIEW-*.md` / `JOURNAL-*.md`, +shared `DECISIONS.md` / `DEFERRED.md`, and the `ADVERSARY-INBOX.md` / `BUILDER-INBOX.md` +side-channels. This is enforced in the kickoff (`launch.py build_kickoff`), the loop prompts, and +the loops' own `AGENTS.md`. If the orchestrator ever sees such a file at the root, move it into +`machine-docs/` and check the kickoff/prompts still mandate it. (The watchdog's `resolve_state` and +INBOX handoff already read `machine-docs/` first, so this is the single canonical home.) + ## Launch & supervise the loops - **Source of truth for the loops:** `cc-ci-plan/plan.md` (mission, Definition of Done, §1.5 diff --git a/cc-ci-plan/launch.py b/cc-ci-plan/launch.py index 109cce0..0fa3298 100644 --- a/cc-ci-plan/launch.py +++ b/cc-ci-plan/launch.py @@ -247,15 +247,22 @@ def build_kickoff(role, idx): f"now; it defines this phase's mission and Definition of Done.\n" f"The general loop protocol still applies and lives in /srv/cc-ci/cc-ci-plan/plan.md " f"(§6.1 coordination, §7 pacing, §9 guardrails) — read those sections too.\n" - f"Track loop state in PHASE-NAMESPACED files in your repo clone: {status}, " - f"BACKLOG-{pid}.md, REVIEW-{pid}.md, JOURNAL-{pid}.md. DECISIONS.md is shared (append).\n" - f'"Done" for this phase = the Builder writes "## DONE" to {status} ONLY after every ' - f"Definition-of-Done item is Adversary-verified with a fresh PASS in REVIEW-{pid}.md " - f"(handshake per §6.1).\n" + f"Track loop state in PHASE-NAMESPACED files UNDER machine-docs/ in your repo clone " + f"(create the dir if missing): machine-docs/{status}, machine-docs/BACKLOG-{pid}.md, " + f"machine-docs/REVIEW-{pid}.md, machine-docs/JOURNAL-{pid}.md. machine-docs/DECISIONS.md " + f"is shared (append).\n" + f"FILE-LOCATION RULE (mandatory): ALL coordination / loop-state files live in " + f"machine-docs/, NEVER the repo root — that includes STATUS/BACKLOG/REVIEW/JOURNAL " + f"(phase-namespaced), DECISIONS.md, DEFERRED.md, and the ADVERSARY-INBOX.md / " + f"BUILDER-INBOX.md side-channels. If you ever find one at the root, git mv it into " + f"machine-docs/.\n" + f'"Done" for this phase = the Builder writes "## DONE" to machine-docs/{status} ONLY after ' + f"every Definition-of-Done item is Adversary-verified with a fresh PASS in " + f"machine-docs/REVIEW-{pid}.md (handshake per §6.1).\n" f"The repo's Phase-1 STATUS.md / BACKLOG.md / REVIEW.md are HISTORY from the completed " f"Phase 1 — do NOT use them as your state; use the phase-namespaced files above.\n" f'Wherever the standing rules below say "plan.md"/"STATUS.md"/"BACKLOG.md"/"REVIEW.md", ' - f"substitute the phase plan and these phase-namespaced files.\n\n" + f"substitute the phase plan and these machine-docs/ phase-namespaced files.\n\n" f"=== standing role & rules ===\n" ) role_prompt = (Path(PLAN_DIR) / "prompts" / f"{role}.md").read_text() diff --git a/cc-ci-plan/plan.md b/cc-ci-plan/plan.md index 2acfe2b..f8097f6 100644 --- a/cc-ci-plan/plan.md +++ b/cc-ci-plan/plan.md @@ -61,8 +61,9 @@ Do these in order. Each step is idempotent; re-running is safe. the server (`/etc/nixos` or existing flake), installed packages, whether Docker/Swarm/abra already exist, DNS that already points at the box. This is the rollback reference. -4. **Seed the loop state files** (§7) if absent: `STATUS.md`, `BACKLOG.md`, `REVIEW.md`, - `JOURNAL.md`, `DECISIONS.md`. Give `BACKLOG.md` two H2 sections — `## Build backlog` +4. **Seed the loop state files** (§7) if absent, ALL under `machine-docs/` (never the repo + root): `machine-docs/STATUS.md`, `machine-docs/BACKLOG.md`, `machine-docs/REVIEW.md`, + `machine-docs/JOURNAL.md`, `machine-docs/DECISIONS.md`. Give `BACKLOG.md` two H2 sections — `## Build backlog` (populated from §5 milestones) and `## Adversary findings` (empty) — per the single-writer rule in §6.1. @@ -239,7 +240,10 @@ cc-ci/ │ ├── architecture.md │ ├── runbook.md # debugging failed runs │ └── baseline.md # bootstrap snapshot -├── STATUS.md BACKLOG.md REVIEW.md JOURNAL.md DECISIONS.md # loop state (§7) +├── machine-docs/ # ALL loop-state/coordination files live here (§7), NEVER repo root: +│ │ # STATUS-*.md BACKLOG-*.md REVIEW-*.md JOURNAL-*.md (phase-namespaced) +│ │ # DECISIONS.md DEFERRED.md ADVERSARY-INBOX.md BUILDER-INBOX.md +│ └── ... └── .drone.yml # pipeline for cc-ci's own repo (lint/self-test) ``` diff --git a/cc-ci-plan/prompts/adversary.md b/cc-ci-plan/prompts/adversary.md index ce878a6..c838535 100644 --- a/cc-ci-plan/prompts/adversary.md +++ b/cc-ci-plan/prompts/adversary.md @@ -10,6 +10,7 @@ LIVENESS PROTOCOL (the watchdog ENFORCES this — see plan.md §7): Credentials/access: §1.5 is the authoritative map. Provided creds are in /srv/cc-ci/.testenv and ~/.ssh; reach cc-ci with `ssh cc-ci` (root, direct tailnet peer — no proxy). Hit the dashboard / *.ci.commoninternet.net via regular HTTP(S) from the VM (uses public DNS, no proxy needed). Verify from a COLD START but you may rely on this shared access path. You run as a SEPARATE process and coordinate ONLY through the git repo per §6.1: +- FILE-LOCATION RULE: ALL coordination / loop-state files live under `machine-docs/`, NEVER the repo root — phase-namespaced STATUS/BACKLOG/REVIEW/JOURNAL, plus DECISIONS.md, DEFERRED.md, and the ADVERSARY-INBOX.md / BUILDER-INBOX.md side-channels. If you find any such file at the root, `git mv` it into `machine-docs/`. - Keep your OWN clone at /srv/cc-ci/cc-ci-adv. If the repo doesn't exist yet, wait and retry on your next wake — the Builder creates it during §1 Bootstrap. - git pull --rebase before every edit; commit; push; never --force. - COMMIT-PREFIX CONVENTION (the watchdog depends on it for handoff signalling). Prefix every commit that records a **verdict or finding** with `review(...)` (e.g. `review(2w): ... PASS`/`... FAIL`). The watchdog watches origin/main and pings the Builder the moment a `review(...)` commit lands — that IS the handoff signal, so your verdict is only reliably picked up if its commit is prefixed `review(`. (The Builder's gate claims are `claim(...)`.) `review(` is load-bearing. diff --git a/cc-ci-plan/prompts/builder.md b/cc-ci-plan/prompts/builder.md index 8ca7417..f0528db 100644 --- a/cc-ci-plan/prompts/builder.md +++ b/cc-ci-plan/prompts/builder.md @@ -10,6 +10,7 @@ LIVENESS PROTOCOL (the watchdog ENFORCES this — see plan.md §7): - **Compact proactively.** If context usage climbs high (≳80%), run `/compact` before continuing — your loop state is in git + phase STATUS/REVIEW, so compaction is lossless and prevents wedging (garbled output / failed tool calls) at the context limit. You run as a SEPARATE process from the Adversary loop and coordinate ONLY through the git repo per §6.1: +- FILE-LOCATION RULE: ALL coordination / loop-state files live under `machine-docs/`, NEVER the repo root — phase-namespaced STATUS/BACKLOG/REVIEW/JOURNAL, plus DECISIONS.md, DEFERRED.md, and the ADVERSARY-INBOX.md / BUILDER-INBOX.md side-channels. Create `machine-docs/` if missing; if you find any such file at the root, `git mv` it into `machine-docs/`. - git pull --rebase before every edit; make the smallest change; commit; git push. Never --force. - COMMIT-PREFIX CONVENTION (the watchdog depends on it for handoff signalling). Prefix every commit with its conventional type. CRITICALLY: prefix a commit that **claims a gate** with `claim(...)` (e.g. `claim(2w): ...`). The watchdog watches origin/main and pings the Adversary the moment a `claim(...)` commit lands — that IS the handoff signal, so a gate claim is only reliably picked up if its commit is prefixed `claim(`. (Verdicts from the Adversary are `review(...)`.) Keep using the other types too (`feat/fix/status/journal/decisions/chore/inbox(...)`), but `claim(` is load-bearing. - Write ONLY your files: source/config, STATUS.md, JOURNAL.md, DECISIONS.md, and the "## Build backlog" section of BACKLOG.md. Treat REVIEW.md and "## Adversary findings" as read-only — the Adversary owns them.