129 lines
6.8 KiB
Markdown
129 lines
6.8 KiB
Markdown
|
# ISO Workflow Manifest Conventions
|
||
|
|
|
||
|
|
This repo is the producer of operator-USB workflow artifacts. Colibri and
|
||
|
|
operator dashboards consume the JSON manifests, summaries, and referenced logs;
|
||
|
|
they do not scrape terminal scrollback as the contract.
|
||
|
|
|
||
|
|
## Common rules
|
||
|
|
|
||
|
|
All ISO workflow manifests SHOULD include these top-level fields:
|
||
|
|
|
||
|
|
| Field | Meaning |
|
||
|
|
| ----------------------------- | ------------------------------------------------------------------------------- |
|
||
|
|
| `schema` | Stable schema id, for example `clawdie.iso.publish.v1` |
|
||
|
|
| `project` | `clawdie-iso` |
|
||
|
|
| `workflow` | Skill or script name that produced the manifest |
|
||
|
|
| `run_id` | Unique run id; include UTC time and commit or artifact stem when possible |
|
||
|
|
| `status` | `pass`, `fail`, `warn`, or `skipped` |
|
||
|
|
| `actor` | Responsible role or operator-visible identity |
|
||
|
|
| `host` | Host that performed the workflow |
|
||
|
|
| `branch` / `commit` | ISO repo branch and commit when a checkout is available |
|
||
|
|
| `started_at` / `completed_at` | UTC ISO-8601 timestamps; use `null` when unknown |
|
||
|
|
| `inputs` | Artifact URLs, image paths, package lists, device ids, or report paths consumed |
|
||
|
|
| `checks` | Array or object of named checks with pass/fail status and concise details |
|
||
|
|
| `outputs` | Manifest path, public URLs, copied reports, or produced artifact paths |
|
||
|
|
| `logs` | Paths to raw logs. Do not inline large logs. |
|
||
|
|
| `summary` | Short human-readable result suitable for Colibri activity text |
|
||
|
|
|
||
|
|
Secrets, API keys, auth keys, private SSH keys, and full unredacted environment
|
||
|
|
dumps MUST NOT be written into manifests. If a workflow uses a secret, record a
|
||
|
|
boolean such as `tailscale_auth_key_baked: true` or a public fingerprint only.
|
||
|
|
|
||
|
|
## Canonical schema ids and paths
|
||
|
|
|
||
|
|
| Workflow | Schema | Canonical output path |
|
||
|
|
| ---------------------- | ------------------------------ | --------------------------------------------------------------------------------------------- |
|
||
|
|
| ISO build | `clawdie.iso.build.v1` | `tmp/colibri/iso-build/<run_id>.json` and `tmp/colibri/iso-build/latest.json` |
|
||
|
|
| ISO publish | `clawdie.iso.publish.v1` | `tmp/output/<image>.manifest.json` |
|
||
|
|
| Flash verification | `clawdie.iso.flash.v1` | `tmp/colibri/iso-flash/<run_id>.json` and `tmp/colibri/iso-flash/latest.json` |
|
||
|
|
| Mounted validation | `clawdie.iso.validation.v1` | `tmp/colibri/iso-validation/<run_id>.json` and `tmp/colibri/iso-validation/latest.json` |
|
||
|
|
| Hardware report ingest | `clawdie.iso.hardware.v1` | `tmp/colibri/iso-hardware/<run_id>.json` and `tmp/colibri/iso-hardware/latest.json` |
|
||
|
|
| Package audit | `clawdie.iso.package-audit.v1` | `tmp/colibri/iso-package-audit/<run_id>.json` and `tmp/colibri/iso-package-audit/latest.json` |
|
||
|
|
|
||
|
|
`tmp/colibri/` is repo-local scratch/output state. It is intentionally not
|
||
|
|
committed. When a result must survive across hosts, commit a concise handoff
|
||
|
|
summary under `doc/` or publish the manifest with the image artifact.
|
||
|
|
|
||
|
|
## Workflow-specific fields
|
||
|
|
|
||
|
|
### `clawdie.iso.build.v1`
|
||
|
|
|
||
|
|
Use for the build result, not for the embedded image manifest alone. Include:
|
||
|
|
|
||
|
|
- build command and flags
|
||
|
|
- FreeBSD version/architecture
|
||
|
|
- source branch/commit/dirty state
|
||
|
|
- Colibri staging mode and artifact directory when `FEATURE_COLIBRI=YES`
|
||
|
|
- output image path, compressed image path when present, checksum path when present
|
||
|
|
- static checks run before build (`sh -n`, markdown format, Colibri preflight)
|
||
|
|
- build log path under `tmp/`
|
||
|
|
|
||
|
|
The image itself also carries
|
||
|
|
`/usr/local/share/clawdie-iso/build-manifest.json`; that file is for runtime
|
||
|
|
inspection from the live USB and does not replace the workflow result manifest.
|
||
|
|
|
||
|
|
### `clawdie.iso.publish.v1`
|
||
|
|
|
||
|
|
Produced by `scripts/write-artifact-manifest.sh`. Include:
|
||
|
|
|
||
|
|
- compressed image, checksum file, and manifest names
|
||
|
|
- SHA256 of the compressed image
|
||
|
|
- raw and compressed sizes when known
|
||
|
|
- public URLs when published
|
||
|
|
- checksum verification status
|
||
|
|
- publish host, actor, branch, and commit
|
||
|
|
|
||
|
|
### `clawdie.iso.flash.v1`
|
||
|
|
|
||
|
|
Use for Hermes USB/IMG Deployer verification and flashing. Include:
|
||
|
|
|
||
|
|
- consumed publish manifest URL/path
|
||
|
|
- downloaded image/checksum paths
|
||
|
|
- checksum and `gzip -t` results
|
||
|
|
- selected whole-disk device, model, serial when available, and size
|
||
|
|
- explicit confirmation that the target is a whole disk, not a partition
|
||
|
|
- flash command summary and post-flash sync/eject result
|
||
|
|
|
||
|
|
### `clawdie.iso.validation.v1`
|
||
|
|
|
||
|
|
Use for static or mounted-image validation on the FreeBSD build host. Include:
|
||
|
|
|
||
|
|
- image path and mount device/slices inspected
|
||
|
|
- SDDM, `clawdie-live-gpu`, `mdo`, CLI, seed-slice, no-blank, power, and panel
|
||
|
|
asset checks
|
||
|
|
- validation limitations, especially that mounted inspection is not graphical
|
||
|
|
hardware proof
|
||
|
|
|
||
|
|
### `clawdie.iso.hardware.v1`
|
||
|
|
|
||
|
|
Use for real-machine live USB reports. Include:
|
||
|
|
|
||
|
|
- hardware model, BIOS/UEFI version when collected, CPU, GPU, network, audio,
|
||
|
|
input summary
|
||
|
|
- `/var/log/clawdie-live-gpu.log` outcome
|
||
|
|
- GL renderer, SDDM/XFCE status, power/no-blank status
|
||
|
|
- `hw-report` output path and public `hw-probe` URL if the operator uploaded it
|
||
|
|
- operator-observed pass/fail notes for touchpad, Wi-Fi, audio, and display
|
||
|
|
|
||
|
|
### `clawdie.iso.package-audit.v1`
|
||
|
|
|
||
|
|
Use for package-list hygiene. Include:
|
||
|
|
|
||
|
|
- package list file audited
|
||
|
|
- package category (`boot-critical`, `operator-workflow`, `diagnostic`, or
|
||
|
|
`candidate-to-defer`)
|
||
|
|
- package size and flat size from the FreeBSD package database or archive
|
||
|
|
metadata
|
||
|
|
- reason kept and deferral risk
|
||
|
|
|
||
|
|
## Handoff expectations
|
||
|
|
|
||
|
|
- Skills should print the manifest path and a concise summary when they finish.
|
||
|
|
- If a workflow is manual-only, write the manifest from the collected facts before
|
||
|
|
handing off to another role.
|
||
|
|
- Raw logs stay in `tmp/` or with the published artifact; markdown handoffs should
|
||
|
|
quote only the exact failure lines needed for follow-up.
|
||
|
|
- Build, publish, and mounted validation remain FreeBSD-owner workflows. Flashing
|
||
|
|
remains Hermes-owned. Live hardware proof remains operator/Codex hardware
|
||
|
|
validation, not static inspection.
|