# Spec-first image generation — the contract template, the run sheet, and the scoring arithmetic

Companion artifact to the project "Generate an image from a spec, then
audit it blind" at
https://lyceumagents.com/projects/spec-first-image-generation/

The syndicate is `config/agents/examples/image_production.yaml` in the
melchizedek-agents repo (https://github.com/jhwadman/melchizedek-agents),
mirrored verbatim at
https://lyceumagents.com/downloads/image-production-syndicate.md. The
observer's protocol and the audit schema are at
https://lyceumagents.com/downloads/visual-inventory-protocol.md.

Needs: Node 22+, the repo, and a Gemini key on a tier that serves the
image model (the free tier errors at generation; the two-phase discipline
still runs without it).

---

## 1. The request — write it so a stranger could grade it

Before you type anything, fill this in. Every line must be checkable
by someone who never read your request.

| field | your value | checkable? (count / name / phrase) |
|---|---|---|
| subject, with an exact count | | |
| arrangement (evenly spaced, centered, stacked…) | | |
| color palette (named colors, or monochrome on X) | | |
| background (one phrase) | | |
| medium (photograph / vector render / oil on canvas…) | | |
| aspect ratio | | |
| lighting (one phrase) | | |

Cut anything that is an adjective ("professional", "elegant",
"contemplative"). It cannot match and cannot fail.

## 2. The run sheet

```bash
npm run syndicate:image
# 1. type the request → read the JSON payload (Phase 1) → edit fields until ≥5 are checkable
# 2. approve in so many words ("build it") → generate_image runs once → note the outputs/ path
# 3. "review the image" → inspect_image(path) → the blind inventory
#                       → SpecAuditor(spec + inventory) → JSON verdict
```

Watch for, in the trace:
- `generate_image` called BEFORE your approval → a Phase-1 violation; count it.
- `inspect_image` called with anything besides the path → impossible by
  schema; if you see spec text in the call, the tool changed.
- the designer describing or grading the image itself → a mandate
  violation; count it.

## 3. The scoring arithmetic

```
fields            = number of entries in verdict.fields
unverifiable      = entries with verdict "unverifiable"
checkable         = fields − unverifiable
matches           = entries with verdict "match"
conformance       = round(100 × matches / checkable)
```

The course's run: 8 fields, 1 unverifiable, 4 matches → 4/7 → 57.
Compare your computed number with the auditor's `conformance`. A
mismatch between the two is an auditor bug, found by recomputing.

## 4. The verdict sheet

| field | expected (spec) | observed (inventory) | verdict | if mismatch: observation or comparison? |
|---|---|---|---|---|
| | | | | |
| | | | | |
| | | | | |

"Observation" = the inventory is wrong about the image (blindness does
not stop a miscount). "Comparison" = the inventory is right and the
auditor judged it wrongly. Read the two quoted lines to decide.

## 5. Closing an `unverifiable`

Never let the auditor see the image. Widen the observer instead:
- add the missing measurement to the inventory protocol (pixel
  dimensions and their reduced ratio is the usual one);
- re-run the review on the SAME file;
- confirm the field now reads match or mismatch.

## 6. The regeneration loop

- take the ONE field the recommendation named;
- reinforce it in the payload (Phase 1 again); approve; generate;
- review and score; compare with the previous score;
- if the score did not move, the generator is not reading that field —
  look at `generation_prompt_string`, the only field it consumes.