feat(scengen): add crypt-admin binary with graph-first scenario generation (DES-027)

[jmf-pobox]

Summary

• New crypt-admin binary with generate, validate, and export subcommands for graph-first scenario authoring (DES-027)
• New internal/scengen/ package: Graph types with 6-direction compass, TopologySource interface, TreeSource filesystem adapter (with hub insertion for >5 children), Visitor pattern for content decoration, YAML directory exporter, SQLite store for iterative authoring
• YAML directory format: scenarios can be a directory with manifest + region files; scenariodir.Load() tries directory format first, falls back to single-file
• Security hardening: path traversal protection in LoadDir, ID collision detection in TreeSource, atomic temp-dir writes in exporter, explicit flag value validation in CLI

Context

Hand-authoring a 200-room scenario in YAML produced 83 broken one-way connections (PR #45). Root cause: YAML embeds edges inside nodes, so each connection must be authored twice. Graph-first generation produces valid bidirectional connections by construction.

Test plan

• 47 new unit tests across 7 test files (go test -race ./internal/scengen/... ./internal/scenario/... ./internal/scenariodir/...)
• Graph validation: bidirectionality, max degree 6, BFS connectivity, unreachable nodes
• Tree adapter: simple/nested trees, file skipping, hub insertion for 8+ children, ID collision detection, empty/missing roots
• YAML round-trip: Generate → WriteYAMLDir → LoadDir → scenario.Validate
• SQLite round-trip: SaveGraph → LoadGraph with meta, nodes, edges, FK/CHECK constraints
• Path traversal: region paths cannot escape scenario directory
• End-to-end: crypt-admin generate --topology tree → crypt-admin validate
• No SQLite in cryptd: go list -deps ./cmd/cryptd | grep sqlite returns empty
• make check passes (vet + test + lint + markdownlint on changed files)

🤖 Generated with Claude Code

---

Note

High Risk
Large, cross-cutting change that adds a new authoring binary with SQLite dependency, introduces a new directory-based scenario format, and modifies core engine combat/leveling/item logic; regressions could affect gameplay balance, scenario loading, and daemon tool compatibility.

Overview
Introduces a new crypt-admin binary (generate, validate, export) for graph-first scenario authoring (DES-027), including optional SQLite-backed working copies and YAML directory export/validation.

Adds support for a directory-based scenario format (manifest + regions/*.yaml) and updates scenario resolution/validation flows (including deprecating cryptd validate and adding server-side default scenario handling).

Expands core gameplay mechanics for balance tuning (DES-028): armor damage reduction, consumable use_item support (engine + daemon tool + rules interpreter + loop events), and point-buy character creation with CON-based HP scaling, plus a new eval-balance monkey-test harness for running large parallel balance simulations.

^{Written by Cursor Bugbot for commit a0281b8. This will update automatically on new commits. Configure here.}

[Copilot]

Pull request overview

Adds a new authoring workflow centered on graph-first scenario generation (DES-027), introducing a crypt-admin binary and the supporting internal/scengen package, plus a new directory-based scenario format loader/exporter.

Changes:

• Introduces crypt-admin (generate, validate, export) and deprecates cryptd validate.
• Adds internal/scengen graph model, topology sources (filesystem tree), visitors, YAML directory exporter, and SQLite store.
• Adds directory-format scenario loading (scenario.LoadDir) and updates scenariodir.Load to prefer directory format over legacy single-file YAML.

Reviewed changes

Copilot reviewed 25 out of 26 changed files in this pull request and generated 14 comments.

Show a summary per file

File	Description
cmd/crypt-admin/main.go	New authoring CLI for generate/validate/export workflows.
cmd/cryptd/main.go	Deprecation warning + blocks validating directory-format scenarios.
internal/scengen/generator.go	Topology→graph pipeline and direction assignment logic.
internal/scengen/generator_test.go	Tests for generation, direction assignment, and tree source integration.
internal/scengen/graph.go	Core graph types, invariants, and validation.
internal/scengen/graph_test.go	Unit tests for graph behavior and validation.
internal/scengen/topology.go	TopologySource interface + raw node/edge types.
internal/scengen/tree.go	Filesystem tree topology source + hub insertion.
internal/scengen/tree_test.go	Tests for tree walking, hub insertion, and ID sanitization/collisions.
internal/scengen/visitor.go	Visitor interface + DescriptionVisitor for room content seeds.
internal/scengen/visitor_test.go	Tests for DescriptionVisitor behavior.
internal/scengen/export.go	YAML directory exporter (manifest + region files).
internal/scengen/export_test.go	Round-trip tests: Generate/Export → LoadDir → Validate.
internal/scengen/store.go	SQLite persistence for iterative authoring (crypt-admin only).
internal/scengen/store_test.go	Store round-trip + FK/CHECK constraint tests.
internal/scenario/loaddir.go	Directory-format scenario loader with traversal checks + duplicate room detection.
internal/scenario/loaddir_test.go	Tests for LoadDir (valid, traversal, duplicate room).
internal/scenariodir/scenariodir.go	Scenario ID resolution updated to prefer directory format.
internal/scenariodir/scenariodir_test.go	Tests for precedence, traversal rejection, directory loading.
go.mod	Adds modernc SQLite driver and related indirect deps.
go.sum	Dependency hash updates for new module additions.
Makefile	Builds third binary (crypt-admin) and cleans it.
README.md	Documents three binaries and crypt-admin usage.
DESIGN.md	Adds DES-027 ADR describing graph-first generation and formats.
CHANGELOG.md	Changelog entries for crypt-admin, directory format, and deprecation.
.beads/issues.jsonl	Updates roadmap/issues entries related to scenario tooling.

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}