DevRunbook-Public/docs/39-reference-composer-and-golden-fixtures.md

39 — Reference composer and golden prompt fixtures

Purpose

The prose composition specification defines behavior, but an autonomous implementation also needs byte-level examples. scripts/reference_compose.py is a small offline specification implementation that renders every P0 minimal example into canonical Markdown.

It is not production application code. The TypeScript composer may use a different architecture, but it must reproduce the fixture contract or deliberately version the contract with migration and snapshot updates.

Included evidence

examples/rendered-prompts/ contains:

• one canonical rendered prompt for each of the 28 P0 packages;
• manifest.json containing source references, byte sizes and SHA-256 digests;
• the canonical heading list and reference-generator version.

The manifest validates against schemas/rendered-prompt-manifest.schema.json.

Reference behavior

The script demonstrates:

• deterministic input interpolation;
• stable canonical heading order;
• repository-profile projection;
• untrusted-evidence warning;
• protected path and repository policy rendering;
• autonomy-specific decision behavior;
• ordered workflow, validation, failure and reporting blocks;
• explicit unavailable-command behavior;
• UTF-8 and LF output;
• SHA-256 calculation over final bytes.

The production engine must additionally implement every rule in documents 08, 28 and 29, including conditions, policy precedence, provenance spans, lint findings, compatibility resolution and immutable persistence.

Commands

Regenerate fixtures after an intentional contract change:

python3 scripts/reference_compose.py

Verify without modifying files:

python3 scripts/reference_compose.py --check

validate_pack.py performs the check automatically. Generated fixture files must not be edited by hand.

Change policy

A fixture change requires:

1. explanation in CHANGELOG.md;
2. updated reference generator when behavior changed;
3. updated manifest and hashes;
4. application snapshot changes;
5. compatibility review for historical generated tasks;
6. proof that the change is intentional rather than nondeterminism.