theslopmachine 0.6.2 → 0.7.0

package/assets/slopmachine/scaffold-playbooks/docker-baseline.md

@@ -0,0 +1,189 @@
+# Docker Baseline Scaffold Playbook
+
+Use this playbook when a scaffold needs a reusable Docker-first baseline rather than product-specific feature work.
+
+## Goal
+
+Ship a Docker/Compose baseline that is honest, reusable, and already verified in a minimal frontend + backend + database lab.
+
+## Runtime contract
+
+- required runtime command: `docker compose up --build`
+- preferred readiness check in automation: `docker compose up --build --wait`
+- required broad test command: `./run_tests.sh`
+- no `.env` dependency for the baseline itself
+
+Verified lab: `/Users/yohannesakd/code/eaglepoint/demonstration/scaffold-lab/docker-baseline`
+
+## Compose defaults
+
+- use `compose.yaml`
+- set an explicit project name with `name:` or require a clean `COMPOSE_PROJECT_NAME`
+- expose only one app-facing edge service to the host by default
+- keep backend, worker, and database services on the internal bridge network only
+- put test runners behind a `test` profile or run them with `docker compose run --rm ...`
+- use `depends_on: condition: service_healthy` for readiness gating, not just start order
+- keep runtime defaults in Compose only when they are clearly local-only and non-sensitive
+
+## Known good service shape
+
+- `frontend`: edge/static or reverse-proxy container; only host-published service
+- `backend`: app container; internal only; healthchecked over localhost inside container
+- `db`: stateful service with named volume and native healthcheck
+- `tester`: containerized verification runner, excluded from default runtime path
+
+## Dockerfile patterns
+
+- use slim official base images
+- run as non-root where practical
+- copy dependency manifests before source to preserve build cache hits
+- use BuildKit cache mounts for package managers when supported
+- keep entrypoints single-purpose and deterministic
+- prefer one process per container
+
+Lab patterns that worked:
+
+- backend: `python:3.12-slim`, non-root `appuser`, `pip` cache mount, `CMD ["python", "-m", "app.server"]`
+- frontend: `nginxinc/nginx-unprivileged:1.27-alpine`
+
+## Secret / bootstrap rules
+
+- baseline must not require a checked-in `.env`
+- never bake production secrets into images or Compose
+- for local-only scaffold bootstrap, generate any disposable credentials or runtime values into ignored files or Docker-managed runtime state instead of checking placeholder literals into tracked files
+- production or shared-environment secrets must come from external overrides, secret stores, CI injection, or generated ignored files
+- document every required secret/input explicitly instead of relying on hidden env state
+
+## Port / network rules
+
+- bind host ports to loopback by default: `127.0.0.1:HOST_PORT:CONTAINER_PORT`
+- prefer high, low-collision local ports
+- publish only the edge service to host
+- use `expose` for internal services instead of `ports`
+- use one explicit bridge network unless the scaffold has a real reason for more
+
+Known good lab default:
+
+- frontend published on `127.0.0.1:18080:8080`
+- backend exposed internally on `8000`
+- Postgres exposed internally on `5432`
+
+## Healthcheck / readiness rules
+
+- every long-running runtime service gets a real healthcheck
+- database healthcheck should use its native readiness command (`pg_isready`, `mysqladmin ping`, etc.)
+- backend healthcheck should hit an in-container localhost readiness endpoint that checks critical dependencies
+- edge service healthcheck should hit its own local health endpoint
+- downstream services should wait on upstream health, not arbitrary sleeps
+- `docker compose up --build --wait` is the honest CI/readiness path
+
+Known good lab behavior:
+
+- db healthy first
+- backend starts only after db healthy and its `/healthz` performs a real Postgres query
+- frontend starts only after backend healthy
+
+## Cache / volume guidance
+
+- use named volumes only for mutable service state that should survive container replacement
+- use build cache mounts for package manager caches
+- avoid bind-mounting package caches as a default scaffold behavior
+- keep test runners stateless and disposable
+- default cleanup path should support `docker compose down -v --remove-orphans`
+
+Known good lab defaults:
+
+- named volume: Postgres data only
+- build cache mount: pip cache in backend image build
+
+## `./run_tests.sh` containerization rules
+
+- `./run_tests.sh` owns the portable broad-path verification
+- it should start the stack with `docker compose up -d --build --wait`
+- it should run a dedicated test container with `docker compose run --rm tester`
+- it should clean up containers, networks, and named volumes on exit
+- tests should verify edge reachability, backend readiness, and database connectivity from containers, not just static lint output
+
+Known good lab behavior:
+
+- `tester` uses the backend image plus a mounted verification script
+- runtime stack stays out of the test profile
+- cleanup removes one-off tester containers before `down`
+
+## Verification commands actually run
+
+All commands below were executed against the lab directory above.
+
+```bash
+docker compose -f "/Users/yohannesakd/code/eaglepoint/demonstration/scaffold-lab/docker-baseline/compose.yaml" config
+
+docker compose -f "/Users/yohannesakd/code/eaglepoint/demonstration/scaffold-lab/docker-baseline/compose.yaml" up -d --build --wait
+
+curl -fsS "http://127.0.0.1:18080/api/message"
+
+./run_tests.sh
+
+python3 - <<'PY'
+import signal
+import subprocess
+import time
+from urllib.request import urlopen
+
+cwd = "/Users/yohannesakd/code/eaglepoint/demonstration/scaffold-lab/docker-baseline"
+proc = subprocess.Popen(["docker", "compose", "up", "--build"], cwd=cwd)
+error = None
+try:
+    deadline = time.time() + 180
+    while time.time() < deadline:
+        try:
+            with urlopen("http://127.0.0.1:18080/healthz", timeout=2) as response:
+                if response.status == 200:
+                    print("frontend healthz reached while docker compose up --build was active")
+                    break
+        except Exception as exc:
+            error = exc
+        time.sleep(2)
+    else:
+        raise RuntimeError(f"frontend healthz never became ready: {error}")
+finally:
+    proc.send_signal(signal.SIGINT)
+    try:
+        proc.wait(timeout=30)
+    except subprocess.TimeoutExpired:
+        proc.kill()
+        proc.wait(timeout=30)
+    subprocess.run(["docker", "compose", "down", "-v", "--remove-orphans"], cwd=cwd, check=True)
+PY
+```
+
+Observed results:
+
+- `docker compose config` resolved cleanly
+- `docker compose up -d --build --wait` reached healthy frontend/backend/db state
+- `curl` returned the proxied backend payload through the frontend edge container
+- `./run_tests.sh` passed and printed `Verified frontend, backend, and database baseline.`
+- the interactive `docker compose up --build` path reached frontend readiness before shutdown
+
+## Recommended defaults to reuse later
+
+- Docker-first runtime contract with `docker compose up --build`
+- `compose.yaml` plus explicit project naming
+- one host-published edge service, loopback-bound, high port
+- internal-only backend and db with `expose`
+- healthchecks on every runtime service
+- readiness-gated `depends_on`
+- non-root containers where practical
+- build cache mounts for dependencies; named volumes only for persistent state
+- containerized `./run_tests.sh` with disposable tester service
+- no `.env` dependency in the baseline itself
+
+## Acceptance checklist
+
+Baseline is acceptable when:
+
+- `docker compose up --build` works
+- `./run_tests.sh` works
+- the sample proves frontend/backend/db composition
+- host port exposure is minimal and loopback-bound
+- healthchecks drive readiness cleanly
+- the baseline does not rely on `.env`

package/assets/slopmachine/scaffold-playbooks/docker-shared-contract.md

@@ -0,0 +1,334 @@
+# Docker Shared Contract For Scaffold Families
+
+This document defines the **shared Docker contract** that every scaffold family must satisfy.
+
+It is **not** one universal `compose.yaml`. Different scaffold families may need different service graphs, images, profiles, and host helpers. The shared requirement is that every scaffold exposes the same **honest, reusable contract surface** to owners and developers.
+
+Applies to:
+
+- web scaffolds
+- backend/API scaffolds
+- Android scaffolds
+- iOS-on-Linux scaffolds
+- desktop scaffolds
+
+## Core contract
+
+Every scaffold family must provide and document these two commands:
+
+- `docker compose up --build`
+- `./run_tests.sh`
+
+Those commands must be:
+
+- real
+- repeatable
+- containerized
+- documented in `README.md`
+- honest about what they do and do **not** prove
+
+Recommended automation/readiness variant:
+
+- `docker compose up --build --wait`
+
+The required user-facing runtime command remains:
+
+- `docker compose up --build`
+
+## What `docker compose up --build` must prove
+
+`docker compose up --build` must prove that the scaffold's primary Docker-backed baseline is wired correctly.
+
+That proof differs by family, but it must always be **meaningful**:
+
+- **web/backend:** a real long-running runtime becomes healthy and reachable through the intended edge surface
+- **Android:** a real containerized build/support environment works, and any claimed preview/dev/support service becomes healthy
+- **iOS-on-Linux:** a real Linux-verifiable build/export/support path works without pretending to prove native Xcode runtime
+- **desktop:** a real containerized build/package/smoke path works without pretending Docker proves a native interactive desktop session by itself
+
+At minimum, `docker compose up --build` must prove all of the following:
+
+- images build from source in the repo
+- declared runtime or support services start without hidden host setup
+- readiness can be observed through healthchecks, predictable logs, or explicit successful artifact production
+- the stack reaches a meaningful healthy state without manual container surgery
+- rerunning the command is predictably convergent
+
+`docker compose up --build` does **not** need to prove full product completion. It **does** need to prove that the baseline scaffold is operational and honest.
+
+## What `./run_tests.sh` must prove
+
+`./run_tests.sh` owns the **broad portable verification path**.
+
+It must prove that the scaffold can be verified from a clean-enough developer or CI environment without relying on undocumented host tools beyond Docker and the documented baseline prerequisites.
+
+`./run_tests.sh` should, as appropriate for the family:
+
+- build or reuse the Compose images
+- start any required services with Compose
+- wait for real readiness
+- run the scaffold's minimum real tests
+- run smoke checks against the actual baseline contract
+- clean up one-off test containers and temporary runtime state
+
+`./run_tests.sh` must not be a fake wrapper that only prints TODOs, only runs lint when runtime proof is expected, or silently skips the meaningful part of verification.
+
+Minimum proof by family:
+
+- **web:** served app shell or app endpoint is reachable, plus real test/build verification
+- **backend:** readiness endpoint and one persistence/integration-shaped path are proven, plus real tests
+- **Android:** Linux-portable build/test path is proven, plus any claimed support service or artifact generation
+- **iOS-on-Linux:** Linux-portable shared-code tests/typechecks/build-shape proof is real, with scope limits stated clearly
+- **desktop:** build/package/smoke path is real, with at least one honest automated desktop-adjacent smoke proof when claimed
+
+## Meaningful healthy state
+
+A scaffold is in a meaningful healthy state when it has crossed from “containers started” into “baseline contract actually proven.”
+
+Healthy state must mean one of these, depending on family:
+
+### Runtime-serving families
+
+For web and backend scaffolds, healthy means:
+
+- long-running services are up
+- dependency services are healthy first
+- app/edge service is healthy after its dependencies
+- the intended smoke route, readiness route, or entry surface actually responds successfully
+- the stack is not crash-looping
+
+### Build/support families
+
+For Android, iOS-on-Linux, and desktop scaffolds, healthy may mean:
+
+- a long-running support service is healthy and usable, **or**
+- a containerized build/export/package/smoke flow completed successfully and produced the documented artifact/output, **or**
+- both
+
+If the family cannot honestly prove native runtime from Linux or Docker alone, the healthy state must stop at the strongest truthful boundary and document that boundary.
+
+Healthy does **not** mean:
+
+- container process exists but no readiness proof exists
+- only dependencies are up while the app/tooling contract is still unusable
+- manual shelling into containers is required to finish bootstrap
+- the stack is “probably fine” because logs look quiet
+
+## Loopback host binding defaults
+
+When a service is published to the host, default to loopback-only binding:
+
+- `127.0.0.1:HOST_PORT:CONTAINER_PORT`
+
+Default expectations:
+
+- prefer loopback over `0.0.0.0`
+- prefer one edge-facing published service when an edge exists
+- prefer high or automatically assigned local ports to reduce collisions
+- if no host-facing service is needed, publish **no** ports
+
+Deviations from loopback-only defaults must be intentional and disclosed in `README.md`.
+
+## Port exposure rules
+
+- publish only the minimum host surface required for the scaffold's honest baseline
+- use `expose` for internal-only services
+- databases, workers, and internal APIs should stay off the host unless the prompt explicitly requires host access
+- Android/iOS-on-Linux/desktop scaffolds may publish zero host ports when the Docker path is build/support oriented rather than user-runtime oriented
+- if multiple published ports are necessary, `README.md` must explain why each exists
+
+The default posture is: **minimal, loopback-bound, owner-readable exposure**.
+
+## Healthchecks and readiness rules
+
+Every long-running service that matters to the baseline must have a real readiness strategy.
+
+Preferred rules:
+
+- use Compose healthchecks for long-running services
+- use native readiness commands for infrastructure services when available (`pg_isready`, `mysqladmin ping`, etc.)
+- use in-container localhost readiness endpoints or commands for app services
+- gate dependent services with health-based readiness, not arbitrary sleep loops
+- use `docker compose up --build --wait` in automation when available
+
+Readiness must be tied to actual usefulness:
+
+- a backend readiness check should verify critical dependencies it claims are required
+- a web edge readiness check should confirm the served surface is actually available
+- a support service readiness check should confirm the advertised support function is actually usable
+
+If a family relies on a one-shot build/export container instead of a long-running service, the success condition must be explicit and documented:
+
+- expected artifact path
+- expected exit status
+- expected follow-up smoke proof, if any
+
+## Cache and volume strategy
+
+Use caches and volumes to make reruns materially faster without hiding state in surprising places.
+
+Rules:
+
+- use **named volumes** for mutable runtime state that should survive container replacement
+- use **BuildKit cache mounts** for package-manager and compiler caches when supported
+- keep disposable test containers stateless by default
+- do not require developers to manually pre-create cache directories
+- do not make ordinary reruns depend on bind-mounted host cache internals
+
+Good default uses for named volumes:
+
+- database data
+- generated local-only runtime config or bootstrap state
+- tool caches that are intentionally persisted across runs and clearly documented
+
+Avoid by default:
+
+- bind-mounting whole home directories
+- bind-mounting package-manager caches as the main scaffold strategy
+- persisting everything just to mask slow builds
+
+## BuildKit and cache-mount guidance
+
+Dockerfiles should be written to reward reruns.
+
+Preferred guidance:
+
+- copy dependency manifests before copying full source trees
+- use slim official base images unless the platform genuinely needs something heavier
+- enable BuildKit-friendly layers and cache mounts for package managers and build tools
+- keep image stages single-purpose and deterministic
+- avoid invalidating heavy dependency layers for every source edit
+
+Typical cache-mount examples include:
+
+- npm/pnpm/yarn caches
+- pip/uv caches
+- Gradle caches
+- Cargo registry/target caches when appropriate
+- compiler/build caches where they are stable and worth persisting
+
+The contract goal is qualitative:
+
+- first run may be heavier
+- reruns should be materially faster
+- reruns should not look like full clean-room rebuilds unless the user explicitly asked for that
+
+## No `.env` policy
+
+Baseline scaffolds must not depend on a checked-in `.env` or hidden env-file workflow.
+
+Required stance:
+
+- no committed `.env`
+- no required manual `cp .env.example .env` step just to make the scaffold baseline work
+- no hidden reliance on developer shell exports that are not documented
+
+If configuration is needed, prefer:
+
+- safe local defaults in Compose for non-sensitive values
+- generated ignored config files
+- mounted secret files
+- Docker-managed volumes for runtime-generated local bootstrap state
+- external overrides for non-baseline environments
+
+## Secret and bootstrap policy
+
+Secrets and bootstrap inputs must be explicit, non-magical, and safe.
+
+Rules:
+
+- never bake real secrets into images, Compose files, or the repo
+- never require undocumented host-side secret setup for the baseline local path
+- local bootstrap must generate any required local-only runtime values into ignored paths or Docker-managed runtime state instead of pre-seeding placeholder literals into tracked files
+- production or shared-environment secrets must come from external secret stores, CI injection, ignored generated files, or explicit operator overrides
+- bootstrap generation must be idempotent and predictable
+
+Acceptable bootstrap behavior:
+
+- generate local-only config into ignored paths or Docker-managed volumes
+- create empty local databases or seed minimal non-sensitive baseline state
+- generate disposable internal-network credentials at runtime when they are clearly local-only, documented, and not written into tracked files
+
+Unacceptable bootstrap behavior:
+
+- hidden interactive prompts during normal Compose startup
+- writing secrets into tracked files
+- requiring users to guess missing inputs from failures
+
+## First-run vs rerun expectations
+
+The contract is qualitative but strict enough to guide owner acceptance.
+
+### First run
+
+First run may reasonably include:
+
+- pulling base images
+- installing dependencies
+- building the initial toolchain layers
+- one-time local bootstrap generation
+
+First run must still be:
+
+- reasonable for a scaffold baseline
+- visibly progressing
+- documented if a specific platform stack is known to be heavier than usual
+
+### Reruns
+
+Reruns must be:
+
+- predictably convergent
+- materially faster than first run in ordinary cases
+- free from repeated heavyweight bootstrap that should have been cached or persisted
+
+## What must not happen
+
+The shared contract forbids these failure patterns by default:
+
+- hour-long silent hangs or long silent stalls without visible progress
+- repeated full SDK/toolchain reinstall on ordinary reruns
+- default clean builds on every run when cacheable layers should have been reused
+- hidden setup steps outside documented commands
+- hidden dependence on host-global state
+- fake healthchecks that only prove a process exists
+- fake `./run_tests.sh` wrappers that skip meaningful runtime/build proof
+- crash-looping services presented as acceptable because Compose eventually started
+- requiring owners to manually exec into containers to finish bootstrap
+- publishing unnecessary host ports
+- pretending Docker proves native mobile or desktop runtime when it does not
+
+If the stack has an unavoidable expensive step, the scaffold must say so plainly and still keep reruns as efficient as reasonably possible.
+
+## Required README disclosures
+
+Every scaffold `README.md` must disclose the shared Docker contract in scaffold-specific terms.
+
+At minimum, `README.md` must state:
+
+- this is a scaffold/baseline and not full product completion
+- what `docker compose up --build` proves for this family
+- what `./run_tests.sh` proves for this family
+- the expected healthy state
+- any published host ports and why they exist
+- loopback-only default behavior when ports are published
+- any meaningful proof boundary Docker cannot cross for this family
+- config/bootstrap behavior without `.env`
+- where secrets come from in local vs non-local environments
+- any known heavy first-run behavior worth expecting
+- cleanup expectations if volumes or caches are intentionally retained
+
+## Owner acceptance checklist
+
+A scaffold family satisfies this shared contract when all of the following are true:
+
+- `docker compose up --build` is real and meaningful
+- `./run_tests.sh` is real and meaningful
+- healthy state is observable and honest
+- host exposure is minimal and loopback-bound by default
+- readiness uses real healthchecks or explicit successful one-shot proof
+- cache and volume strategy supports materially faster reruns
+- the scaffold does not depend on `.env`
+- secret/bootstrap behavior is explicit and safe
+- the baseline does not hide setup or repeated heavyweight reinstall work
+- `README.md` tells the truth about scope, proof, limits, and operator expectations

package/assets/slopmachine/scaffold-playbooks/electron-vite-default.md

@@ -0,0 +1,124 @@
+# Electron Vite Default Scaffold Playbook
+
+Use this playbook for desktop app requests unless the prompt or existing repo clearly dictates another desktop stack.
+
+## Goal
+
+Create a simple Electron baseline that:
+
+- uses Electron + Vite + TypeScript by default
+- has an honest Linux Docker verification wrapper
+- has a portable broad test/build wrapper
+- wires the baseline desktop test path without pretending the product is complete
+
+## Runtime contract
+
+- required Docker command: `docker compose up --build`
+- required broad test command: `./run_tests.sh`
+- both commands must be real and working
+- `./run_app.sh` may exist as a helper for host-side convenience, but it does not replace the required Docker baseline
+
+## Safe default stack
+
+- Electron
+- Vite
+- TypeScript
+- selected local test runner
+- Playwright Electron support or equivalent when UI-bearing proof is part of the baseline test shape
+
+## Verified baseline notes
+
+From a real lab verification on 2026-04-14:
+
+- the official `@quick-start/electron` `vanilla-ts` bootstrap is a good starting shape, but it is interactive even when the template is passed, so scaffold automation should expect prompt handling or a follow-up hardening pass
+- the generated starter's default dependency set did not install cleanly in this environment via plain `npm install`; the verified baseline pinned current working Electron/tooling versions and replaced the generated `@electron-toolkit` runtime helpers with a small explicit preload bridge
+- for Linux-oriented desktop scaffold, treat `docker compose up --build` as a meaningful containerized build/package/smoke gate rather than pretending it proves a native long-running desktop runtime
+- the practical convergence strategy was **multi-stage Docker verification**: run lint/unit/package/headless-smoke during image build, then start a tiny long-running report service from the verified artifacts so Compose can reach a stable healthy state instead of exiting immediately after a one-shot container
+- pin the Docker toolchain explicitly (the verified lab used `node:24.13.0-bookworm-slim` plus pinned Electron/electron-vite/electron-builder/Playwright versions)
+- keep Linux packaging at scaffold stage to `electron-builder --linux dir` so verification stays real but time-bounded
+- use Xvfb plus Playwright's `_electron` support for the minimum real headless desktop smoke path inside Docker
+- use BuildKit cache mounts for npm, Electron, and electron-builder caches so reruns are materially faster and avoid repeated heavyweight downloads
+
+## Required scripts
+
+- `docker compose up --build`
+- `./run_tests.sh`
+- `./run_app.sh` when useful for host-side convenience
+
+## Preferred Docker strategy for desktop baseline
+
+For Linux desktop scaffolds, prefer this shape unless the prompt requires something heavier:
+
+1. **verify stage** in the Dockerfile that runs:
+   - dependency install from lockfile
+   - lint/type/unit checks as applicable
+   - `electron-vite build`
+   - `electron-builder --linux dir`
+   - one headless Electron smoke test under Xvfb
+2. **runtime/report stage** that copies only the verified artifacts and a tiny report/health surface.
+3. Compose service healthcheck that validates the verification summary and packaged artifact still exist.
+4. Optional loopback-only report port if it helps operators inspect proof without shelling into the container.
+
+This keeps `docker compose up --build` honest and reusable:
+
+- first run may be heavier
+- reruns should reuse cached layers/downloads
+- Compose ends in a stable healthy service instead of an immediately exited verification container
+- the stack does not claim Docker proves full interactive desktop runtime
+
+## Security baseline
+
+At scaffold, preserve the safe desktop defaults:
+
+- `contextIsolation` on
+- no unnecessary `nodeIntegration` in renderer
+- preload boundary explicit
+- prefer `sandbox` on unless the existing app or prompt explicitly requires a different choice
+
+## Minimal real test floor
+
+At scaffold, include at least:
+
+- one real unit or renderer/main-process test
+- one real build/smoke invocation in `./run_tests.sh`
+- one honest Docker-backed runtime/build path behind `docker compose up --build`
+- for Linux-oriented Electron baseline, prefer one pure unit test plus one headless Electron smoke test that launches the built app through Playwright under Xvfb
+- package proof should stay at the strongest honest/time-bounded Linux checkpoint, usually `electron-builder --linux dir`
+
+## README floor
+
+`README.md` must already state:
+
+- scaffold status versus implemented scope
+- required Docker command: `docker compose up --build`
+- broad test command: `./run_tests.sh`
+- desktop-only scope and current proof boundary
+- host-side helper command: `./run_app.sh` when present
+- main process / preload / renderer layout at a high level
+- expected healthy state after Compose converges
+- any loopback-only port used by a report/support service and why it exists
+- first-run versus rerun expectations when Docker caches are intentionally used
+
+## Common pitfalls
+
+- unsafe renderer defaults
+- pretending scaffold proves full desktop interaction quality
+- skipping the broad Linux build/test path
+- leaving runtime/test commands dependent on undocumented host setup
+- leaving the default generator dependency versions unverified
+- making Linux packaging too heavy at scaffold time by requiring deb/snap/AppImage before the baseline is proven
+- using a one-shot verification container as the only Compose service so `docker compose up --build` exits instead of converging to a stable healthy state
+- forcing repeated clean installs/downloads on ordinary reruns when BuildKit cache mounts or layered installs would avoid it
+
+## Acceptance checklist
+
+Scaffold is acceptable when:
+
+- `docker compose up --build` works
+- `./run_tests.sh` works
+- safe desktop defaults are preserved
+- baseline desktop tests exist
+- README is honest
+- the Docker path proves build, unpacked Linux packaging, and one real headless Electron window smoke check
+- the Compose path reaches a stable healthy state that truthfully represents the verified boundary
+- reruns avoid obvious full clean-room rebuild loops except when dependency manifests or toolchain pins actually change