2026-03-14

What shipped today

Today was about turning a finally-playable Phantasmagoria build into something we can trust and explain. The key shift was architectural: instead of letting the generator implicitly define what “valid” YAML means, I locked the project around the real product boundary. The renderer and rendered-mod linter are now treated as the stable public surface, and the repo explicitly describes the four-stage pipeline as generation, content/source lint, renderer, and rendered-mod lint. That change turned a lot of fuzzy tribal knowledge into a concrete contract.

That showed up in several practical ways. I wrote down the v1 YAML contract in WORKING_MOD_CONTRACT.md, added hand-authored known-good and known-bad fixture releases, and taught validate_release.py to point authors toward the contract and the example fixtures when source validation fails. The docs now answer a hand-author’s question directly: what do I run on YAML, what do I run on a rendered mod, and what patterns are actually supported in v1.

I also removed wrapper ambiguity from the day-to-day workflow. The Makefile layer and validate_mod.py wrapper are gone from the live path, and the canonical renderer entrypoint is now stellaris_mod_renderer.py, which finally matches stellaris_mod_linter.py. CI, README, contributor docs, and the contract docs all speak that same language now. The broader value is clear: Phantasmagoria is no longer just “the AI mod generator project.” It has a more believable renderer/linter core that can support monthly releases and eventual extraction into a cleaner open-source tool surface.

Completed

• #137 Define and document the supported YAML contract for the v1 renderer/linter
• #138 Define the Phantasmagoria content/source-lint layer separately from rendered-mod lint
• #139 Promote the canonical renderer CLI to stellaris_mod_renderer.py

Release progress

• v1: 3/6 closed. Open: #140, #141, #142.
• v1.5: 0/1 closed. Open: #136.
• v2: 0/2 closed. Open: #135, #112.

Carry-over

• Merge situation-progress-descriptions back to main; issues #137, #138, and #139 are closed, but the work is still on the feature branch right now.
• #140 Document Phantasmagoria namespace and ID allocation rules for monthly releases.
• #141 Align source validation with the documented v1 YAML contract.
• #142 Clarify or fix validate_outcomes.py --release for the current events/ layout.
• Decide whether #136 stays parked behind the v1 contract work or gets pulled forward once the v1 milestone is steadier.

Risks

• The v1 YAML contract is now documented more tightly than validate_release.py enforces; #141 exists because that mismatch can still confuse hand-authors.
• validate_outcomes.py --release ... is currently misleading against the live events/ layout; use --file for spot checks until #142 lands.
• Situation code still exists as dark code, but it is not part of the supported v1 surface. The docs are clearer now, but it would still be easy to accidentally slide back into treating situations as “almost supported.”

Flags and watch-outs

• stellaris_mod_renderer.py is now the canonical renderer command. scripts/render.py is the implementation module, not the public surface.
• validate_outcomes.py is Phantasmagoria-specific content QA, not a generic linter.
• Makefile and scripts/validate_mod.py are intentionally gone from the live workflow; if they reappear in docs or CI, treat that as regression drift.

Next session

• Merge or PR situation-progress-descriptions so the contract/CLI cleanup actually lands on main.
• Prep and exec #140 to finish the mod-identity side of the v1 architecture story.
• Prep and exec #141 so source validation matches the newly documented contract.
• Prep and exec #142 or otherwise fix validate_outcomes.py --release so the content-lint layer behaves honestly with the current repo layout.