Statblock generation guidance: schema descriptions + system prompt

[Drakosfire]

Why

Statblock generation guidance lived in one 8-line prose blob in the user message, covering maybe 3 of the 43 domain validators. The schema channel — the thing the model reads at the moment it writes each field — was switched off by a stale premise. Post-b645019, domain-invalid output is no longer a terminal failure; it is GM hand-editing in the Workbench, so every avoided validator error is avoided toil.

Plan: Docs/Plans/HANDOFF-pr26-statblock-generation-prompt-and-schema-guidance.md.

What changed

• Schema channel unlocked. description is no longer stripped from the OpenAI strict artifact; the highest-density validator fields now carry guidance, led by the usage-kind field matrix. title stays stripped (Pydantic generates it from the class name for nothing). A compiler guard fails closed on $ref siblings (OpenAI rejects them; caught only by the live lane).
• Prompt split into system + user. Conventions moved to a stable build_system_prompt(edition) organized around the validator clusters that actually fire: cardinality, usage-kind exclusivity, derived math, reference discipline, attack shape, section/activation pairs, spell-group rules. The user message is pure task data. PROMPT_VERSION → v4.
• Worked examples. A WORKED_EXAMPLES block (usage shapes, multiattack, legendary actions) appended to the system prompt; both+ex ablation arm measures it.
• Model policy. structured_generation → statblock_frontier (gpt-5.6-luna). The falsification series showed mini's residual failures were capability-bound: Luna cut error incidences −71% on the hard fixture (5.6 → 1.6 codes/trial).
• Falsification harness at scripts/statblock_prompt_eval.py — five ablation arms, error-severity validator codes as the metric, --dump-definitions for payload post-mortems.
• Fixture provenance. Published candidate/revise fixtures regenerated at v4; fixture tests now assert prompt_version == PROMPT_VERSION so provenance drift fails loudly.

Evidence

Description support in strict mode was verified empirically (live calls), not assumed. Iterated falsification on thornvault-regent (legendary + spellcasting hard fixture): mini saturated at 0/10 clean across six guidance configurations (USAGE_FIELDS + SPELL_GROUP_SLOTS pinned; payload dumps showed prose/typed mismatches no text channel moved). Luna + the spell-slots placement line: 4/5 clean, 0.2 codes/trial (from 0/10, 5.6 on mini at session start). Sole residual: UNKNOWN_PHASE_REFERENCE 1/5.

Live gate: test_openai_accepts_the_published_strict_artifact passes against the regenerated artifact.

Test plan

• uv run pytest tests/statblocks_v1/ -q (290 passed)
• Live OpenAI acceptance lane (3 passed)
• Harness confirmation run on shipping config (Luna, 4/5 clean)
• Known unrelated CI failure: import-time OpenAI() initialization baseline (pre-existing on main)
• After merge: retarget stacked feat(statblocks_v1): server-owned derived math (prompt v5) #27 to main

[Drakosfire]

Review verdict: changes required before merging the base of the stack.

The system/user prompt split, retained schema descriptions, live strict-schema acceptance test, and fail-closed $ref sibling guard are directionally sound. The stack relationship with #27 is also correct.

Two contract problems remain:

1. The schema and system channels contradict each other for Usage.kind == "manual". The field-local resource_key description says it must be null for every non-resource kind, while the enum guidance, system prompt, and validator deliberately permit resource_key for manual. Since this PR's purpose is to align those channels, the contradiction should be resolved and covered by a consistency assertion.
2. The published generation fixtures are stale. Runtime provenance is statblock-generation-prompt-v4, but both candidate-response.json and revise-replay-response.json still publish v3. The exporter constructs the candidate through GenerationServiceV1, so a true regeneration would carry v4. Regenerate both fixtures and add a test tying fixture provenance to PROMPT_VERSION; the existing fixture tests only prove model validity/coherence, not freshness.

Also update the PR description before merge: it says the prompt moved to v2 and structured_generation ships on gpt-5.4-mini, while the head actually uses prompt v4 and maps the policy to gpt-5.6-luna. That is audit/provenance drift even if the final model choice is intentional.

The failing Actions run is still the known unrelated import-time OpenAI() collection failure.

[Drakosfire]

Blocking — this field-local instruction contradicts the actual manual contract. UsageKind says manual may carry uses/resource_key, the system prompt repeats that, and _validate_usage intentionally leaves both optional for manual. “Must be null for every other kind” tells the model the opposite in the schema channel. Please enumerate the kinds that actually forbid it and explicitly preserve manual as optional; add a test that the schema and prompt matrices agree.

[Drakosfire]

Blocking — published provenance is stale. PROMPT_VERSION at this head is v4, and export_fixture_pack() creates this candidate through the live GenerationServiceV1, so a regenerated fixture would say v4. revise-replay-response.json is stale in the same way. Regenerate both and add a fixture assertion against PROMPT_VERSION so future prompt bumps cannot silently leave consumer examples behind.

[Drakosfire]

Review addressed in 10cfddf:

1. Schema/prompt contradiction on manual usage — Usage.resource_key description now reads "Required for kind 'resource'… Optional for kind 'manual'; must be null for every other kind." Matches the enum doc, the system prompt matrix, and the validator (which checks nothing on manual beyond recharge_range). Checked uses too — its description never excluded manual, so it was already consistent. Schema artifacts, OpenAPI, and TS client regenerated.
2. Stale fixture provenance — candidate + revise fixtures regenerated at prompt v4, and both fixture test files now assert generation_receipt.prompt_version == PROMPT_VERSION, so the next bump fails loudly instead of drifting. PR description refreshed to head (v4, gpt-5.6-luna routing, worked examples, current evidence).

Lane: 290 passed; live artifact acceptance: 3 passed.

[Drakosfire]

Stack Review 2 — no blockers

Both findings from Stack Review 1 are resolved correctly.

• Usage.resource_key guidance now agrees across the field description, UsageKind documentation, the system prompt, and validator semantics: required for resource, optional for manual, null otherwise.
• Candidate and revision fixtures now carry prompt v4 provenance, their schema fingerprints were regenerated with the description change, and fixture tests bind the checked-in receipt to PROMPT_VERSION so future drift fails loudly.
• The PR body now describes the actual shipping prompt/model configuration.

I found no new correctness or stack-contract issue in 10cfddf. PR 26 is ready to merge from code review. The failing repository workflow remains the known unrelated import-time OpenAI() baseline.