Turn \"draw our method figure\" from a one-shot gamble into the same audited spiral the framework uses for\ncomics: a blueprint is the source of truth, the image model bakes the look, a cross-model panel + a\ndeterministic diff keep it honest, and the loop converges to a publication-grade figure that is\nreproducible (re-run the blueprint) and auditable (a trace of every round).
\nTwo things are simultaneously true: (a) gpt-image-2 CAN render a clean Figure-1 with legible labels when\nconditioned on a labeled blueprint — do not assume it garbles text; (b) on a free prompt it DRIFTS\n(renames phases, invents nodes, garbles a token, leaves pasted-looking floating labels). The blueprint +\nblind-transcribe-then-hard-diff loop turns (a) into a reliable result and catches (b) every round.
\n system description ─▶ ① BLUEPRINT (JSON content-lock) ── validate_blueprint.py\n ▼\n ② CONDITION (white-bg labeled SVG → PNG) + identity sheet (real chibi, optional) ── render_condition.py --png\n ▼\n ③ BAKE — agent: mcp__codex__codex(prompt+abs ref paths+out_path, workspace-write, gpt-5.5, config{xhigh}) → gpt-image-2 native PNG ── pickup_image.py --out-existing (sig+size+dims, mtime-bound, HARD-VETO struct/zlib/PIL/SVG, fail-closed)\n ▼\n ④ PANEL — Gemini ‖ Codex BLIND-transcribe → content_diff.py (observed ⊖ blueprint) → Claude structural sign-off\n ▼\n ⑤ agent reads the diff + the panel blockers → re-bake re-asserting the locked labels\n ▼\n converged? ─ no ─▶ ③ (bounded: max_rounds → escalate to human)\n │ yes\n ▼\n ⑥ APPROVE → figure.png + blueprint.json + trace.jsonl\ngpt-5.5, config: {model_reasoning_effort: xhigh, include_image_gen_tool: true} → the native image_generation\ntool (gpt-image-2). The gpt-5.5 pin is a single hardcoded COMPAT DEFAULT in the bake sidecar payload\n(run_spiral.py mirrors run_comic.py's canonical bake plan; a config-driven model override is PLANNED, not\nyet implemented). It pins the BAKE only — the panel's Codex reviewer is un-pinned (see PANEL below).\nCRITICAL: image_gen is produced ONLY via mcp__codex__codex (the agent tool), NOT\ncodex exec. codex exec / over-specified / forbid-list prompts make Codex hand-draw a code fallback\n(struct+zlib PNG or SVG/matplotlib) — visually indistinguishable for trivial shapes, useless for a real\nmethod-figure. The working invocation is mcp__codex__codex with a dead-simple prompt +\nsandbox: \"workspace-write\" (it must WRITE the out_path) + model: \"gpt-5.5\" +\nconfig: {model_reasoning_effort: \"xhigh\", include_image_gen_tool: true} (the schema has NO top-level effort\nparam; config{xhigh} shorthand below ALWAYS expands to both these keys — without include_image_gen_tool\ncodex won't fire its native image tool, it falls back to descriptive text / an SVG renderer) + cwd: <project>.\nReference images are passed by absolute file path inside the prompt (the schema has NO -i); the output\npath is a deterministic abs path in the prompt. Pick it up with pickup_image.py --out-existing\n(verifies the EXPLICIT out_path: PNG sig + size + dims, mtime >= request.created_at) which HARD-VETOES\nstruct/zlib/PIL/<svg>/matplotlib markers in the agent transcript (fail-closed; there is no 'native sig\nwins' override). Honesty caveat: as of Jun 2026 native headless persistence is unreliable, so this\nfail-closed verifier — not any sandbox setting — is the first guard against a non-native bake. But the\nHARD-VETO is a BEST-EFFORT denylist against the known codex-exec hand-draw fallback (struct/zlib/PIL/\nSVG/matplotlib markers), NOT a complete security boundary — a novel fallback that emits a sig-valid PNG\nwithout those markers can slip past it. The load-bearing faithfulness gate is the cross-model blind-transcribe\npanel + the deterministic content_diff (the pixels are what reviewers transcribe), with this denylist as a\ncheap upstream filter.gemini + codex CLIs as subprocesses\n(both must be on PATH; MCP is ONLY the bake seam): Gemini = gemini --model auto-gemini-3; Codex =\ncodex exec -i <png> with NO model pin (it follows the local codex config — currently gpt-5.6-sol) at\neffort xhigh — so the reviewer model ≠ the bake's pinned gpt-5.5. Plus the deterministic content_diff.\nClaude (this agent) is the post-pass STRUCTURAL sign-off, not a blind transcriber — the loop converges on\nGemini-approve + Codex-approve + empty-diff, then Claude signs off.approve can only diagnose/veto,\nnever be the sole acquitter. ACCEPT requires Gemini approve + Claude structural approve + the hard-diff empty.baked only in v0 — the image model renders ALL text; nothing is hand-pasted.\n(hybrid/overlay — lock structure + vector-overlay the labels for paper zero-tolerance text — are on the\nv1 roadmap; do NOT use a vector overlay as an ad-hoc patch on a finished bake, it reads as pasted.)figures/method_figure/<figure_id>/ (figure.png, blueprint.json, condition.svg, trace.jsonl).mtime >= request.created_at, and the agent transcript shows no struct/zlib/\nPIL/<svg>/matplotlib fallback (pickup_image.py --out-existing, HARD-VETO — a clean sig never overrides a\nfallback marker). This veto is a BEST-EFFORT denylist against the known codex-exec hand-draw fallback,\nNOT a complete security boundary (a novel marker-free fallback could evade it). The load-bearing\nfaithfulness gate remains the cross-model blind-transcribe panel + the deterministic content_diff; the\ndenylist is a cheap upstream filter that matters because native headless persistence is currently unreliable.--bake-mode=agent writes each\nnative PNG to its explicit per-round out_path (no shared dir), so concurrent agent bakes still risk a\nrequest/status sidecar race — keep one runner per figure. (The global ~/.codex/generated_images dir +\nnewest-after-marker pickup that could cross-pollinate concurrent bakes is a hazard of the LEGACY\n--bake-mode=exec path ONLY, which is retired for real bakes.)This skill is pure render + verify. Ownership:
\nrun_spiral.py calls scripts/compile_brief.py\nto map a method_figure_brief.json → a schema-valid blueprint.json + traceability.json, fail-closed (an\nobject that can't trace to a brief field, or a missing claim/number/trait, is refused — not invented). It is\nno longer a manual LLM hop. Full field map + the guards: references/blueprint_authoring.md.FAILED / Logic Drift rather than ship a figure whose pixels contradict the blueprint.The default single input = a method_figure_brief.json (schemas/method_figure_brief.schema.json) —\nONE ARIS-format file; the blueprint, the coordinates, and the identity wiring are all derived. The identity\nsheet is resolved from the brief's identity_refs[].path (no separate --identity to manage). Where the\ninput comes from, in authority order:
method_figure_brief.json — the canonical ARIS hand-off (what paper-plan emits); auto-detected (by\nits schema_version: \"method-figure/brief/v1\") + compiled. ·blueprint.json — power-user override (--from-blueprint, used as-is). ·experiment-plan / paper-write method section / free-text — no brief yet: the agent first DRAFTS a\nmethod_figure_brief.json from it (claims/numbers verbatim; anything missing → Refuse-and-Escalate), then compiles.ARIS integration: the canonical producer is paper-plan — after its claims_matrix it emits the\nmethod_figure_brief (components, flows, phases, the headline claim/number, identity refs, forbidden_tokens).\nYou feed that one file to run_spiral.py; Step-0 compiles it and the traceability is enforced by the\ncompiler (an un-traceable object is a Refuse-and-Escalate, not a render). The identity sheet is created once\nupstream and locked; method-figure only reads it.
Feed ONE method_figure_brief.json; the whole loop is one command (all commands below run from the repo\nroot; the panel shells the gemini + codex CLIs, so both must be on PATH):
python3 skills/method-figure/scripts/run_spiral.py your_method_figure_brief.json --out-dir figures/method_figure/<id>\n# auto-detects a brief → Step-0 compile_brief.py → blueprint.json + traceability.json (deterministic, fail-closed)\n# → validates → renders condition(+png) → [bake (agent: mcp__codex__codex --bake-mode=agent, workspace-write,\n# gpt-5.5 config{xhigh} → gpt-image-2 native PNG via the .bakereq.json sidecar) → pickup_image.py --out-existing\n# verify (fail-closed, HARD-VETO over the status file's mcp_output) → Gemini + Codex blind-transcribe → content_diff → blockers] × rounds\n# → on PANEL-CLEAN writes figure.png + blueprint.json + traceability.json + trace.jsonl.\n# input auto-detect: a brief is detected ONLY by schema_version \"method-figure/brief/v1\" vs a blueprint (version);\n# a bare components+flows JSON with NO schema_version is REFUSED — it REQUIRES --from-brief (fail-closed, no guessing)\n# --identity is OPTIONAL (resolved from the brief's identity_refs[0].path); --dry-run prints the round-1 bake\n# prompt; --p0-only runs the zero-credit gate (validate+compile+render+prompt-lint) then stops; --max-rounds N.\n# There is NO --effort knob (the flag is removed) — bake + review effort are hardcoded xhigh by design.\n# --gemini-cmd overrides how the google-family reviewer is shelled (default: the legacy `gemini` CLI). Legacy\n# CLI dead (IneligibleTierError, 2026-07)? pass --gemini-cmd \"python3 cli/gemini_agy_shim.py\" — the shipped\n# Antigravity shim pins a Gemini model (the second-reviewer slot must stay google-family for quorum honesty).\n\n\nPower-user / override: already have a hand-tuned blueprint?
\nrun_spiral.py blueprint.json --identity sheet.png --out-dir … --from-blueprintruns the legacy path unchanged. A worked example brief lives at\nexamples/method_figure/method_figure_brief.json.\nLong-running (each bake ~3-8 min) — run it in the background; watchtrace.jsonl. It converges to\nPANEL-CLEAN — BOTH reviewers returned parseable JSON, Gemini approve AND Codex approve, the\ndeterministiccontent_diffempty, core scores (incl.character_identitywhen an identity sheet is given)\n≥ threshold, and no anomalies/blockers — then STOPS and hands to the calling agent (Claude) for the final\nstructural sign-off (the generator family never self-acquits). The manual steps below are exactly what\nrun_spiral.pyautomates (run them to debug one stage).
--bake-mode=agent (the agent-wrapper SOP) — REQUIRED for the default mode to functionThe bake is a synchronous sidecar handshake and the skill agent is its fulfiller (without it, every bake\npolls to --bake-timeout and escalates with failure_kind=\"other\" — fail-closed, not a hang, never a false throttle):
python3 skills/method-figure/scripts/run_spiral.py your_brief.json --out-dir figures/method_figure/<id> --bake-mode agent.<out-dir>/ for a new *.bakereq.json (the orchestrator writes round<N>.png.bakereq.json);mcp__codex__codex with exactly its\n{prompt: <prompt_text>, model:\"gpt-5.5\", config:{include_image_gen_tool:true, model_reasoning_effort:\"xhigh\"}, sandbox:\"workspace-write\", cwd:<cwd>}\n(codex writes the native PNG to the sidecar's out_path). The config MUST carry both\ninclude_image_gen_tool:true AND model_reasoning_effort:\"xhigh\": without include_image_gen_tool Codex will\nnot fire its native gpt-image-2 tool (it falls back to a struct/zlib/SVG hand-draw), and xhigh is the\nrequired reasoning tier;request_id from the *.bakereq.json and write <out>.bakestatus.json carrying the status, a\nbounded raw mcp_output, AND that request_id VERBATIM — mcp_output so the HARD-VETO can scan it (the core\nfeeds this file to pickup --transcript; an ok status with no raw output makes the veto INERT), and\nrequest_id because pickup_image.py --out-existing --request-id fail-closes the bake if the status\nrequest_id is missing or mismatched (write it on BOTH ok and fail):\n{\"status\":\"ok\",\"mcp_output\":\"<raw>\",\"request_id\":\"<verbatim from bakereq>\"}, or\n{\"status\":\"fail\",\"failure_kind\":\"throttle\",\"mcp_output\":\"<raw>\",\"request_id\":\"<verbatim from bakereq>\"} on a\n429 / MODEL_CAPACITY_EXHAUSTED / overloaded error (else\n{\"status\":\"fail\",\"failure_kind\":\"other\",\"mcp_output\":\"<raw>\",\"mcp_error\":\"<raw>\",\"request_id\":\"<verbatim from bakereq>\"}).status:\"ok\", via pickup_image.py --out-existing (sig + dims + size >\n500000 + mtime >= created_at, HARD-VETO over mcp_output, and --request-id fail-close if the status\nrequest_id is absent/mismatched). --bake-mode=exec is the legacy/CI non-image path and RAISES if it reaches a real bake.Write blueprint.json per schemas/blueprint.schema.json. The *_exact fields (label_exact, desc_exact,\ngroup/edge/callout *_exact, rail.label_exact) are the LOCKED text re-asserted verbatim every round;\nexpected_tokens[] are what the panel must blind-transcribe and the diff checks. Then:
python3 skills/method-figure/scripts/validate_blueprint.py blueprint.json # jsonschema (if installed) + unique ids · edges resolve · box/group/callout bounds · no dup labels\npython3 skills/method-figure/scripts/render_condition.py blueprint.json --out condition.svg --png condition.png # white-bg labeled layout → rasterized\nPrepare identity_sheet.png from the project's REAL characters if the figure has any (never invent robots).\nThe condition PNG + the identity sheet are the two image references.
Call mcp__codex__codex (sandbox workspace-write — it must WRITE the out_path; model: gpt-5.5,\nconfig: {model_reasoning_effort: xhigh, include_image_gen_tool: true}, cwd: <project>) with the prompt from\nreferences/prompt_templates.md §A — it RE-ASSERTS every *_exact label + the round-N blockers + the carried\npositive_invariants, with condition.png + identity_sheet.png referenced by absolute path inside the\nprompt (the schema has no -i) and the exact out_path to save the native PNG. Write the bake status to\nround<N>.png.bakestatus.json carrying the raw mcp_output (so the HARD-VETO can scan it) AND the\nrequest_id copied VERBATIM from round<N>.png.bakereq.json (pickup --request-id fail-closes if it's\nmissing/mismatched), then verify the explicit out_path (no marker/glob):
python3 skills/method-figure/scripts/pickup_image.py --out-existing --out figures/method_figure/<id>/round<N>.png --min-bytes 500000 --aspect <W/H> --created-at <epoch> --request-id <uuid4 hex from round<N>.png.bakereq.json> --transcript figures/method_figure/<id>/round<N>.png.bakestatus.json\nAsk each of the TWO blind transcribers — Gemini + Codex (references/prompt_templates.md §B) — for the STRICT\nJSON of references/reviewer_protocol.md: they transcribe observed_tokens / observed_edges /\nidentity_audit and an anomalies list (the Negative-Space Audit), NOT shown the expected labels.\nClaude is NOT a transcriber — it never produces a blind round<N>.cc.json; its structural sign-off comes\npost-pass in ⑤/⑥. Save as round<N>.{gemini,codex}.json, then:
python3 skills/method-figure/scripts/content_diff.py blueprint.json round<N>.gemini.json round<N>.codex.json\n# → missing_tokens / unaccounted_tokens / anomalies ; empty == content-accurate\nRead the diff report + the two transcribers' blockers. The executing agent itself merges blockers only\n(ignore nice_to_have — chasing polish makes it oscillate), carries the union of positive_invariants\nforward, and writes the round-N+1 bake prompt.
missing_tokens/anomalies · Gemini approve · Codex approve (required, but\nnever the sole acquitter) · Claude structural approve · every core score ≥ acceptance.min_core_score (default 4).round < MAX_ROUNDS → back to ③.On ACCEPT: copy the approved PNG to figures/method_figure/<id>/figure.png, keep blueprint.json, and append\nto trace.jsonl per round: {round, blueprint_sha, condition_sha, generated_sha, reviewers:{...verdicts}, hard_diff:{missing_tokens,anomalies}, fixes:[...], decision} + a final {final_approve, image, blueprint, accepted_round, verdicts}. Failures are kept — the fixes that were needed are the memory (the figure-wiki).
*_exact label in every regeneration — image\nmodels drift content every round; the blueprint is the anchor.mcp__codex__codex, workspace-write) and fail-closed if no real native PNG at the\nexplicit out_path (pickup_image.py --out-existing, HARD-VETO struct/zlib/PIL/<svg>/matplotlib in the status file's mcp_output).run_spiral.py brief.json --out-dir … --p0-only\n(validate brief → compile blueprint → render condition → confirm the bake prompt carries ALL locked labels,\nthe identity path resolves, the background is white). A blocker caught here costs zero image credits.feedback_gate_identical_scores_judge_broken).| Figure type | \nFit | \n
|---|---|
| method overview / pipeline / architecture / workflow | \nexcellent | \n
| conceptual / taxonomy / comparison diagrams | \ngood | \n
| statistical plots | \nno → plotting tool | \n
| exact-topology deterministic vector figures | \nprefer a pure-vector renderer | \n
| photo-realistic scenes / long narrative comics | \nno (comics use the framework's spiral engine) | \n
A converged worked example ships in examples/method_figure/: the ARIS-Movie-Director Figure 1 — blueprint +\nfigure.png + condition.svg + the real 4-round trace.jsonl (Gemini approve + Codex approve + empty diff, then\nClaude's structural sign-off). PROMPTS.md there\npublishes the exact, unedited prompt sequence that baked it (all 4 gpt-image-2 bakes + the cross-model\ncritiques, paths redacted) — the canonical exhibit of how detailed a condition must be; copy its shape.
scripts/compile_brief.py — Step-0 automation: deterministic method_figure_brief.json →\nblueprint.json + traceability.json (the ADJ-4 field map, auto_layout, fail-closed\nvalidate_traceability). This is what makes the skill single-input — run_spiral.py brief.json auto-detects\nscripts/run_spiral.py — the one-command orchestrator (sniff input → [Step-0 if brief] → bake→pickup→\npanel→diff→consolidate→decide loop to PANEL-CLEAN). --p0-only runs the zero-credit gate;\n--from-brief/--from-blueprint disambiguate. Folds blocker-consolidation + invariant-carry inline.scripts/overlay_labels.py + label_policy: hybrid/overlay — vector-overlay the structured labels on\nthe bake for paper zero-tolerance text. Default stays baked (fully generated).reviewer-independence — reviewers blind-transcribe from the image only; the generator (Codex image_gen) ≠ the visual judges.acceptance-gate — the loop drives, can't acquit: ACCEPT needs the deterministic content-diff clean + Gemini approve + Codex no-veto + Claude structural sign-off.artifact-integrity — the baker doesn't judge its own figure's numbers; the blueprint is ground truth, verified by the blind diff.reviewer-routing — bake sidecar pins Codex gpt-5.5 + xhigh (a\nhardcoded compat default; config-driven override is planned); the CLI reviewers pin NO model (they follow the\nlocal codex config — currently gpt-5.6-sol) at xhigh; Gemini auto-gemini-3; never downgrade effort.review-tracing — every round's reviewer verdicts are logged to trace.jsonl.