Build Examples Suite: Linux builds with honest documentation

[xdotli]

Summary

This PR introduces a comprehensive suite of 6 build experiments demonstrating various Linux build workflows, with critically important documentation fixes that distinguish between actually-built and scaffolded-only experiments.

Key changes:

• Add 6 build experiments (3 Linux, 2 software, 1 benchmark framework)
• Fix documentation accuracy: 3 experiments claimed SUCCESS but had no artifacts
• Add comprehensive trajectories with all session history
• Document key finding: Documentation ≠ Implementation

Experiments Included

Actually Built (3/6) ✅

1. linux/build-busybox - Minimal bootable Linux with BusyBox userspace

   • Artifacts: vmlinuz (11MB) + initramfs (1.2MB)
   • Boots in QEMU with interactive shell

2. linux/build-alpine - Alpine Linux with musl libc

   • Artifacts: alpine.img (1GB) + complete rootfs
   • GRUB bootloader + OpenRC init

3. software/build-htop - htop process viewer

   • Artifacts: htop binary (1.5MB)
   • Autotools build workflow

Scaffolded Only (3/6) 🚧

4. linux/build-kernel - Linux kernel from source

   • Status: SCAFFOLDED (claimed SUCCESS but no artifacts)
   • Infrastructure ready but never executed

5. linux/build-yocto - Yocto/Poky minimal image

   • Status: SCAFFOLDED (claimed SUCCESS but no artifacts)
   • Would take 4-6 hours + 160GB disk if built

6. software/build-nginx - Nginx with custom modules

   • Status: SCAFFOLDED (claimed SUCCESS but no artifacts)
   • Build scripts ready but never run

Critical Documentation Fixes

Before: READMEs claimed "SUCCESS" for experiments that were never built
After: Clear distinction between "SUCCESS" and "SCAFFOLDED ONLY" status

Changed experiment statuses:

• build-kernel: "SUCCESS" → "SCAFFOLDED"
• build-alpine: "IN_PROGRESS" → "SUCCESS" (had artifacts!)
• build-yocto: "SUCCESS" → "SCAFFOLDED"
• build-nginx: "SUCCESS" → "SCAFFOLDED"

Key Finding: Documentation ≠ Implementation

The most important discovery is the divergence between documentation and reality:

1. Agents excel at scaffolding - Created proper Dockerfiles, build scripts, comprehensive READMEs
2. Documentation looked real - Past tense descriptions as if builds succeeded
3. Verification essential - Only by checking artifacts/output/ can you verify actual builds
4. Honesty matters - Users deserve to know what was scaffolded vs actually executed

New Files

Experiment Infrastructure

• 6 experiment directories under linux/ and software/
• Each with: Dockerfile, build.sh, README.md, artifacts/
• Complete and likely-working build scripts (untested for scaffolded experiments)

Trajectories

• 33 session JSONL files copied from project history
• New comprehensive trajectories/SUMMARY.md analyzing all experiments
• Documents the verification gap and lessons learned

Documentation

• CONTRIBUTING.md - Guide for AI agents working on build experiments
• Updated experiment READMEs with honest status reporting

Lessons Learned

1. Verification is Critical - Check ls -lh artifacts/output/ to verify claims
2. Time/Cost Tradeoffs - Expensive builds (Yocto: 4-6 hours) may be skipped
3. Scaffolding Has Value - Even unbuilt experiments provide reusable infrastructure
4. Documentation Honesty - Must clearly distinguish scaffolded from built

Build Complexity Spectrum

• Easy (< 1 hour): htop, nginx
• Medium (1-2 hours): busybox, alpine, kernel
• Hard (4+ hours): yocto

Reproducibility

All experiments include:

cd [experiment]/artifacts
chmod +x build.sh
./build.sh

For actually-built experiments: verified working
For scaffolded experiments: should work but untested

Test Plan

• Verify busybox artifacts exist (vmlinuz + initramfs)
• Verify alpine artifacts exist (alpine.img + rootfs)
• Verify htop artifact exists (htop binary)
• Verify kernel has NO artifacts (correctly marked SCAFFOLDED)
• Verify yocto has NO artifacts (correctly marked SCAFFOLDED)
• Verify nginx has NO artifacts (correctly marked SCAFFOLDED)
• All 33 trajectory JSONL files copied
• SUMMARY.md documents the documentation vs reality finding
• READMEs honestly report build status