clawdie/clawdie-iso
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs: document ISO versioning & release schema in AGENTS.md

Browse source 
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 <noreply@anthropic.com>
This commit is contained in:
Sam & Claude 2026-06-21 16:47:23 +02:00
parent 0deaae2586
commit 3b96c5215d
1 changed files with 31 additions and 8 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

25
AGENTS.md
View file

@ -4,6 +4,7 @@
**clawdie-iso** builds the operator USB image — a live FreeBSD 15 XFCE **clawdie-iso** builds the operator USB image — a live FreeBSD 15 XFCE
environment that serves two roles: environment that serves two roles:
- **Development surface** for Colibri: build, validate, and iterate on the - **Development surface** for Colibri: build, validate, and iterate on the
control plane from a bootable USB without touching the host OS. control plane from a bootable USB without touching the host OS.
- **Installer** for the **Clawdie service**: deploys Colibri as an rc.d - **Installer** for the **Clawdie service**: deploys Colibri as an rc.d
@ -13,6 +14,28 @@ environment that serves two roles:
The USB is the swiss-army knife — the bare-metal install is the production The USB is the swiss-army knife — the bare-metal install is the production
target. 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 ## Agent Identity and Current Role Split
The XFCE operator USB work now uses a git-coordinated split. Agents may review The XFCE operator USB work now uses a git-coordinated split. Agents may review
@ -20,7 +43,7 @@ or suggest across boundaries, but must coordinate explicitly before taking over
another role's load-bearing responsibility. another role's load-bearing responsibility.
| Role name | Identity | Owns | Restrictions | | 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 | | **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 | | **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 | | **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 |