Publish DevRunbook source

2026-09-03 04:09:17 +02:00
commit cfd2804e27
928 changed files with 161642 additions and 0 deletions
@@ -0,0 +1,61 @@
+# 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:
+
+```bash
+python3 scripts/reference_compose.py
+```
+
+Verify without modifying files:
+
+```bash
+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.