From 3b96c5215dd86c8a238dc8baceef43fbfbdf8d98 Mon Sep 17 00:00:00 2001 From: Sam & Claude Date: Sun, 21 Jun 2026 16:47:23 +0200 Subject: [PATCH] docs: document ISO versioning & release schema in AGENTS.md The product-version scheme was only captured in scattered build.cfg/build.sh comments and agent memory. Promote it to contributor-visible guidance: - ISO_VERSION is an explicit product version in build.cfg (0.11.0, unified with Colibri); no-version builds fail fast; image name = codename + version. - Component versions are provenance in build-manifest.json (version_scheme "product"), not the image identity. - BUILD_CHANNEL dev|release; release gate (build.sh:check_release_gate) requires clean staged trees so the manifest fully describes the artifact. Matches shipped code; no behavior change. Co-Authored-By: Claude Opus 4.8 --- AGENTS.md | 39 +++++++++++++++++++++++++++++++-------- 1 file changed, 31 insertions(+), 8 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index db8dacd9..3f0dd952 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -4,6 +4,7 @@ **clawdie-iso** builds the operator USB image — a live FreeBSD 15 XFCE environment that serves two roles: + - **Development surface** for Colibri: build, validate, and iterate on the control plane from a bootable USB without touching the host OS. - **Installer** for the **Clawdie service**: deploys Colibri as an rc.d @@ -13,20 +14,42 @@ environment that serves two roles: The USB is the swiss-army knife — the bare-metal install is the production target. +## Versioning & Release + +The image carries its **own product version**, not one borrowed from a +component. `ISO_VERSION` is set explicitly in `build.cfg` (currently `0.11.0`, +unified with Colibri); a build with no version fails fast. The image name +derives from the FreeBSD codename and this version — e.g. +`clawdie-quindecim-0.11.0.img` (`quindecim` = FreeBSD 15, `build.sh:146`). + +Component versions (clawdie-iso, clawdie-ai, colibri, zot) are **provenance**: +recorded in `build-manifest.json` as `version_scheme: "product"`. They describe +what went into the artifact; they are not its identity. + +`BUILD_CHANNEL` selects the build mode: + +- `dev` (default) — iteration builds; staged repos may be dirty. +- `release` — the published-artifact gate. `build.sh:check_release_gate` + requires every staged source (clawdie-iso, clawdie-ai, colibri, zot) to be a + clean tree (`git status --porcelain`, so untracked files also fail) so the + manifest's recorded commits fully describe the build. This is + reproducibility-by-record, and is separate from any future package-repo + channel (latest/quarterly/signed). + ## Agent Identity and Current Role Split The XFCE operator USB work now uses a git-coordinated split. Agents may review or suggest across boundaries, but must coordinate explicitly before taking over another role's load-bearing responsibility. -| Role name | Identity | Owns | Restrictions | -| ---------------------------------- | ----------------------------------- | -------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | -| **Pi ISO Developer** | Pi harness (this dev agent) | Source changes, docs, static checks, commits, pushes | Does not start ISO builds or flash media unless explicitly assigned | -| **Codex ISO Builder** | codex pkg on the FreeBSD build host | `./build.sh`, mounted-image inspection, publishing, hardware validation | Focuses on targeted changes; broad source refactors require prior review; reports exact logs/output back through git or handoff notes | -| **Hermes USB/IMG Deployer** | Hermes on Debian/Linux | Downloading verified published artifacts, USB target identification, flashing | Only flashes verified artifacts to whole-disk target paths; does not need git-host access | -| **Claude Reviewer / XFCE Tweaker** | Claude (Linux) | Review/plans plus Track E XFCE GUI polish | Builds ISO only through Codex ISO Builder; validates with Linux tooling; marks speculative runtime claims as such | -| **Opencode / Z.ai Integrator** | Opencode CLI on Linux | Linux-side Colibri/dashboard experiments plus Pi/DeepSeek v4 provider-lane validation wiring | Validates on Linux and refers FreeBSD runtime claims to the build host; uses Sam-provided API keys only for provider validation | -| **Operator (Sam)** | Human operator | Product, hardware, acceptance, release judgment | Human approval required for release/tagging decisions | +| Role name | Identity | Owns | Restrictions | +| ---------------------------------- | ----------------------------------- | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | +| **Pi ISO Developer** | Pi harness (this dev agent) | Source changes, docs, static checks, commits, pushes | Does not start ISO builds or flash media unless explicitly assigned | +| **Codex ISO Builder** | codex pkg on the FreeBSD build host | `./build.sh`, mounted-image inspection, publishing, hardware validation | Focuses on targeted changes; broad source refactors require prior review; reports exact logs/output back through git or handoff notes | +| **Hermes USB/IMG Deployer** | Hermes on Debian/Linux | Downloading verified published artifacts, USB target identification, flashing | Only flashes verified artifacts to whole-disk target paths; does not need git-host access | +| **Claude Reviewer / XFCE Tweaker** | Claude (Linux) | Review/plans plus Track E XFCE GUI polish | Builds ISO only through Codex ISO Builder; validates with Linux tooling; marks speculative runtime claims as such | +| **Opencode / Z.ai Integrator** | Opencode CLI on Linux | Linux-side Colibri/dashboard experiments plus Pi/DeepSeek v4 provider-lane validation wiring | Validates on Linux and refers FreeBSD runtime claims to the build host; uses Sam-provided API keys only for provider validation | +| **Operator (Sam)** | Human operator | Product, hardware, acceptance, release judgment | Human approval required for release/tagging decisions | ## Agent / Codebase Check-In Matrix