clawdie/clawdie-iso
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
clawdie-iso/docs/ISO-MANIFESTS.md
Sam & Claude b959b64d21 chore(iso): rename provenance "dirty" → "modified" (Sam & Claude) 
Drop the "dirty" terminology in favor of "modified" (same boolean sense:
true = working tree has uncommitted or untracked changes). Pure rename — no
logic change. Safe now: nothing consumes these keys yet (checked colibri too).

- build-manifest.json keys: zot_dirty/colibri_dirty/iso_repo_dirty
  → zot_modified/colibri_modified/iso_repo_modified
- .clawdie-source.json: dirty_at_build → modified_at_build
- iso-publish manifest (write-artifact-manifest.sh): repo_dirty → repo_modified
- gate messages, comments, shell vars, and docs (BUILD/CHANGELOG/ISO-MANIFESTS/
  PLAN) reworded.

Checks: sh -n on all three scripts; release-gate smoke test PASS; prettier clean
on changed docs.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-06-15 17:06:17 +02:00

6.8 KiB
Raw Blame History

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/modified 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 xz -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.