# Gated build and deployment workflow

## G0 - preflight

1. Identify the project and target board; read its board reference.
2. Hash the user-provided HDF/XSA before copying it.
3. Verify matching tool versions and enough VM/build-disk space.
4. Discover live Windows/VM/board addresses and the TFTP interface. Prove both ping and actual file transfer when available.
5. Capture serial boot output, current environment, QSPI probe, boot mode evidence, MTD layout and current storage without writing.
6. Verify JTAG/power control and a tested recovery method. Stop before erase if recovery is not credible.
7. Capture the build input fingerprint and run the reuse check.

## G1-G3 - build or verified reuse

For a rebuild, create a clean project, import the exact handoff, archive the generated baseline, then apply only reviewed board overlays. Configure an initramfs root filesystem and include at least:

- QSPI/MTD and board Ethernet/PHY support;
- selected SD/eMMC host support;
- `fdisk` or `parted`, `blkid`, FAT formatting, ext4 formatting/checking, `mount`, `umount`, archive, checksum and TFTP tools;
- enough `CONFIG_SYS_BOOTM_LEN` for the uncompressed initramfs.

Build and package with logs and exit codes. Treat warnings about a detected flash differing from the device-tree expectation as unresolved board-profile drift even if access currently works.

Before deployment validate:

- generated DT contains the intended controller nodes and no conflicting alternate controller;
- BOOT.BIN contains exactly the declared components;
- image size fits its partition and DDR load range;
- `qspi_cache.py check` or equivalent delivery validation passes;
- all artifacts have stable size and SHA-256.

## G4 - boot region

Back up the known-good boot image when possible. Prefer the vendor-supported flash programmer with verify. If it fails, use a board-proven JTAG-to-DDR recovery path only after checking its address, size and marker protocol. Never improvise a recovery write on an unverified board.

After programming, fully remove and restore power. Confirm the intended U-Boot banner and QSPI probe. Repeat the cold boot; do not count a warm reset.

## G5 - image region

Use separate checked operations:

1. download the exact image and assert transferred byte count;
2. compute RAM CRC/hash and match the manifest;
3. probe QSPI and assert geometry;
4. erase `ceil(image_bytes / erase_bytes) * erase_bytes`, bounded by the image partition;
5. write exactly `image_bytes`;
6. read back exactly `image_bytes` to a second RAM address;
7. compare CRC/hash and every byte;
8. only then save the QSPI-only bootcmd.

The bootcmd must make the origin unambiguous: probe QSPI, read the declared offset/length, apply only documented board fixes, and boot that RAM address. Do not add silent SD/network fallback unless explicitly required.

## G6 - hardware acceptance

For at least two complete power cycles, retain console evidence of:

- BootROM mode/source evidence, QSPI probe, exact QSPI read offset/length and FIT load;
- Linux release, initramfs mounted as root, expected MTD partitions;
- board Ethernet/PHY identity, live address and real TFTP transfer;
- required storage host registration and device-tree/register evidence;
- required deployment tools.

With removable media inserted, first perform a read-only gate: device enumeration, CID, capacity, partition table, current mounts, and bounded sample reads. Formatting and production deployment are separate destructive phases.