Development

Architecture

cli.py and config.py provide the user entry points. inventory/ resolves candidates. production/ schedules bounded local work and delegates to the original pipeline.CandidateFlow and mode modules:

• modes/with_binary/: reference program, behavioral tests, documentation and output.
• modes/without_binary/: measured environment, repository profile, specification and output.
• execution/: container execution, runtime selection and resumable state.
• agent/: model transport, tools and bounded response delivery.
• verification/: payload checks, optional semantic review and original-consumer replay.

Keep construction changes in these original stages. A new transport or runtime must preserve mode contracts, task isolation and the published grading denominator.

Local checks

python -m pip install -e '.[dev]'
python tools/acceptance/acceptance_tests.py --suite offline --evidence-root /tmp/pg-offline
python tools/acceptance/acceptance_tests.py --suite docker --evidence-root /tmp/pg-docker

Native regression tests need a C/C++ toolchain, CMake, Meson, Ninja, Autoconf, Automake and Libtool. Docker tests use actual containers. Migrated stage fixtures explicitly retain their original small-test settings; public production-default tests independently enforce the full quality requirements.

Reproducible acceptance

Maintainer tools live in tools/acceptance/; they are not runtime commands. The preserved comparison plan and source locks live in its baselines/ directory. Old comparison runs name the exact source commit and any shared patches. A patched old baseline must never be described as an unmodified-old execution. Historical Python tasks with the frozen original grader can be replayed with acceptance_replay.py --legacy-python-consumer /path/to/frozen-old-checkout. The driver checks the full source lock and exact task grader bytes, records this consumer version explicitly, and runs the unchanged task with current quality and execution checks. This option does not apply to non-Python tasks or production. The Python A/B comparison retains both grader hashes. The declared TAP parser addition is accepted only when both hashes match the recorded source snapshots, all original grader syntax is unchanged after removing that addition, and every other scoring payload plus the actual old/new consumer results still match.

Current acceptance permits normal build and quality rejections, records every attempt, and requires enough fully certified tasks in both modes. Historical failures are retained. Replacement tasks have their own source commit, execution and certificate; they do not overwrite the original result. See validation.

After ordinary CLI production, independently inspect all current publications:

python tools/acceptance/cohort.py --config /path/to/programgen.toml --output /evidence/cohort.json

The default requires four certified tasks and two languages in each mode. Normal rejections remain in the report; an all-rejected batch cannot pass. Multiple --config arguments combine separately recorded batches without double-counting candidate identities. The A/B driver has an explicit --allow-rejections scope for accounting for all attempted inputs; its output never certifies task quality. When an earlier execution failure is followed by a fully certified publication of the same immutable candidate, the cohort report retains that error with an explicit resolved_by link. Missing or corrupt published artifacts remain blocking errors until repaired. Required task counts and language coverage are unchanged, and an unrelated successful candidate cannot resolve an error.

Exercise recovery on a dedicated accepted run whose configuration selects only its certified inputs. This tool backs up the outputs, deliberately damages them, and invokes the ordinary CLI to check skipping and restoration:

python tools/acceptance/acceptance_recovery.py --run-root /path/to/run \
  --config /path/to/run/programgen.toml --evidence-root /evidence/recovery

Before freezing a candidate, stage its complete source and generate the package manifest:

python tools/acceptance/check_release.py --write-manifest
python tools/acceptance/check_release.py
python -m build
python tools/acceptance/check_release.py --wheel dist/FILE.whl --sdist dist/FILE.tar.gz

Large raw evidence, credentials, generated tasks and historical investigation records belong outside the source checkout. Report a bug with the commit, redacted configuration, candidate identity, failure stage and relevant log path.

Documentation website

The website is a static view of the Markdown documentation and the commented starter configuration. Its builder, stylesheet and browser interactions live in tools/docs/; no production monitor or application backend is included.

python -m pip install -r tools/docs/requirements.txt
python tools/docs/build.py --output /tmp/programgen-docs
python -m http.server 8000 --directory /tmp/programgen-docs

Keep generated HTML outside the source checkout. Any static host can serve the output directory. Edit the repository documentation to update page content; the starter download always comes from configs/programgen.toml.