docs(design): add DES-027 graph-first scenario generation#46
Closed
docs(design): add DES-027 graph-first scenario generation#46
Conversation
…r pattern Hand-authoring a 200-room scenario produced 83 broken one-way connections. Root cause: YAML embeds edges inside nodes, requiring each connection to be authored twice. Graph algorithms produce valid graphs by construction. DES-027 defines: topology-source agnostic generator, visitor-based content decoration, and SQLite storage for large scenarios. YAML remains for small test fixtures. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
There was a problem hiding this comment.
Pull request overview
Adds a new architectural decision record (DES-027) documenting a “graph-first” approach to scenario generation (generate topology as a graph first, then decorate via visitors), and updates repo docs/metadata to reference the new decision.
Changes:
- Add DES-027 to
DESIGN.mddescribing graph-first generation + visitor-based decoration and storage format recommendations. - Update
CLAUDE.mdandCHANGELOG.mdto reference DES-027. - Update beads issue tracking to add a new validator task and revise the M11.5 epic description.
Reviewed changes
Copilot reviewed 4 out of 4 changed files in this pull request and generated 4 comments.
| File | Description |
|---|---|
| DESIGN.md | Adds DES-027 ADR content (graph-first generation, visitors, storage options). |
| CLAUDE.md | Updates the referenced DES decision count/range to include DES-027. |
| CHANGELOG.md | Adds an “Unreleased → Added” entry referencing DES-027. |
| .beads/issues.jsonl | Adds a new task for topology validation/auto-fixing and updates the M11.5 epic text. |
Comment on lines
+1614
to
+1616
| Bidirectionality is enforced: inserting an edge inserts both directions | ||
| in a single transaction. The 6-direction constraint is enforced by the | ||
| primary key on (node, direction). |
| ## Design Decisions | ||
|
|
||
| **Before proposing any design change, read `DESIGN.md`.** It contains 26 settled decisions (DES-001–026) with alternatives considered and outcomes. Do not revisit a settled decision without new evidence. Log any new decision there before implementing. | ||
| **Before proposing any design change, read `DESIGN.md`.** It contains 27 settled decisions (DES-001–027) with alternatives considered and outcomes. Do not revisit a settled decision without new evidence. Log any new decision there before implementing. |
| {"id":"cryptd-1qj.4","title":"DM narrates for full party","status":"open","priority":4,"issue_type":"task","owner":"jmf@pobox.com","created_at":"2026-03-10T15:34:54.92049-07:00","created_by":"jmf-pobox","updated_at":"2026-03-10T15:34:54.92049-07:00","dependencies":[{"issue_id":"cryptd-1qj.4","depends_on_id":"cryptd-1qj","type":"parent-child","created_at":"2026-03-10T15:34:54.921175-07:00","created_by":"jmf-pobox"}]} | ||
| {"id":"cryptd-23s","title":"Unify toolRegistry and dispatch switch into single tool registration","description":"Replace the decoupled toolRegistry var and dispatch switch with a single registration pattern where each tool registers both its schema and handler function.","status":"open","priority":4,"issue_type":"task","owner":"jmf@pobox.com","created_at":"2026-03-12T12:57:42.679102-07:00","created_by":"jmf-pobox","updated_at":"2026-03-12T12:57:42.679102-07:00"} | ||
| {"id":"cryptd-2z6","title":"M11.5: Scenario Generation Pipeline (DES-025)","description":"Four-phase scenario generation: Topology → Geography → Population → Narrative. Schema extensions for grid coordinates (floor/x/y). Visitor pattern for cross-cutting concerns. Three authoring modes: hand, DM-generated, tool-generated.","status":"open","priority":3,"issue_type":"epic","owner":"jmf@pobox.com","created_at":"2026-03-12T06:17:28.02665-07:00","created_by":"jmf-pobox","updated_at":"2026-03-12T06:17:28.02665-07:00","dependencies":[{"issue_id":"cryptd-2z6","depends_on_id":"cryptd-cft","type":"blocks","created_at":"2026-03-12T06:17:42.449706-07:00","created_by":"jmf-pobox"}]} | ||
| {"id":"cryptd-2pr","title":"Scenario topology validator and auto-fixer","description":"Build a Go tool (or extend cryptd validate) that checks scenario YAML for: (1) one-way connections (room A→B exists but B→A doesn't), (2) rooms with \u003e6 connections needed (6-direction limit), (3) unreachable rooms from starting_room, (4) rooms where all exits lead to full parents. Auto-suggest fixes: add reciprocal connections, insert hub rooms to split overloaded parents, report truly unreachable rooms. This is the 'Topology' phase from M11.5 (cryptd-2z6). Motivated by PR #45 where 200 hand-authored rooms had 83 broken one-way connections.","status":"open","priority":2,"issue_type":"task","owner":"jmf@pobox.com","created_at":"2026-03-15T11:26:40.579854-07:00","created_by":"\"jmf-pobox\"","updated_at":"2026-03-15T11:26:40.579854-07:00"} |
Comment on lines
+1607
to
+1611
| CREATE TABLE room_enemies ( | ||
| node_id TEXT REFERENCES nodes(id), | ||
| enemy_template TEXT, | ||
| FOREIGN KEY (enemy_template) REFERENCES enemy_templates(id) | ||
| ); |
![cursor[bot]](https://avatars.githubusercontent.com/in/1210556?s=60&v=4){kind=small}
There was a problem hiding this comment.
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.
| {"id":"cryptd-1qj.4","title":"DM narrates for full party","status":"open","priority":4,"issue_type":"task","owner":"jmf@pobox.com","created_at":"2026-03-10T15:34:54.92049-07:00","created_by":"jmf-pobox","updated_at":"2026-03-10T15:34:54.92049-07:00","dependencies":[{"issue_id":"cryptd-1qj.4","depends_on_id":"cryptd-1qj","type":"parent-child","created_at":"2026-03-10T15:34:54.921175-07:00","created_by":"jmf-pobox"}]} | ||
| {"id":"cryptd-23s","title":"Unify toolRegistry and dispatch switch into single tool registration","description":"Replace the decoupled toolRegistry var and dispatch switch with a single registration pattern where each tool registers both its schema and handler function.","status":"open","priority":4,"issue_type":"task","owner":"jmf@pobox.com","created_at":"2026-03-12T12:57:42.679102-07:00","created_by":"jmf-pobox","updated_at":"2026-03-12T12:57:42.679102-07:00"} | ||
| {"id":"cryptd-2z6","title":"M11.5: Scenario Generation Pipeline (DES-025)","description":"Four-phase scenario generation: Topology → Geography → Population → Narrative. Schema extensions for grid coordinates (floor/x/y). Visitor pattern for cross-cutting concerns. Three authoring modes: hand, DM-generated, tool-generated.","status":"open","priority":3,"issue_type":"epic","owner":"jmf@pobox.com","created_at":"2026-03-12T06:17:28.02665-07:00","created_by":"jmf-pobox","updated_at":"2026-03-12T06:17:28.02665-07:00","dependencies":[{"issue_id":"cryptd-2z6","depends_on_id":"cryptd-cft","type":"blocks","created_at":"2026-03-12T06:17:42.449706-07:00","created_by":"jmf-pobox"}]} | ||
| {"id":"cryptd-2pr","title":"Scenario topology validator and auto-fixer","description":"Build a Go tool (or extend cryptd validate) that checks scenario YAML for: (1) one-way connections (room A→B exists but B→A doesn't), (2) rooms with \u003e6 connections needed (6-direction limit), (3) unreachable rooms from starting_room, (4) rooms where all exits lead to full parents. Auto-suggest fixes: add reciprocal connections, insert hub rooms to split overloaded parents, report truly unreachable rooms. This is the 'Topology' phase from M11.5 (cryptd-2z6). Motivated by PR #45 where 200 hand-authored rooms had 83 broken one-way connections.","status":"open","priority":2,"issue_type":"task","owner":"jmf@pobox.com","created_at":"2026-03-15T11:26:40.579854-07:00","created_by":"\"jmf-pobox\"","updated_at":"2026-03-15T11:26:40.579854-07:00"} |
There was a problem hiding this comment.
Extra quotes in created_by field value
Low Severity
The newly added cryptd-2pr issue has created_by set to "\"jmf-pobox\"" — the JSON string value is "jmf-pobox" with literal quote characters wrapped around it. Every other entry in the file uses the bare string jmf-pobox without embedded quotes. Any filtering or grouping by created_by will fail to match this entry against the others.
Contributor
Author
|
Superseded by PR #47 which includes the DES-027 ADR along with the full implementation (crypt-admin binary, scengen package, balance tuning). |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Test plan
make checkpasses (markdownlint, go vet, go test)🤖 Generated with Claude Code
Note
Low Risk
Docs-only updates (ADR + changelog + internal issue tracker) with no code or runtime behavior changes, so risk is low aside from potential future implementation expectations.
Overview
Adds DES-027 to
DESIGN.md, formalizing a shift toward graph-first scenario generation (valid-by-construction topology) plus visitor-based content decoration, and recommending SQLite as the scalable storage format (keeping YAML as an export/fixture format).Updates
CHANGELOG.md,CLAUDE.md, and.beads/issues.jsonlto reference DES-027 (including new related tracking items) and to bump the settled design-decision count from 26→27.Written by Cursor Bugbot for commit a51338a. This will update automatically on new commits. Configure here.