Add warning to use ids if release name contains spaces

Author: alexboly

README.md

@@ -86,33 +86,50 @@ Section names are case-insensitive.
 ### Assigning stories to releases
 
 Use the `[release:: name]` field on each story to assign it to a release
-swimlane. The name must match a release defined in the `# Releases` section.
-Stories without a `[release::]` field are parsed but not shown in any swimlane.
+swimlane. The value must match a release name (or id, see below) defined in
+`# Releases`. Stories without a `[release::]` field are parsed but not shown
+in any swimlane.
 
 ```markdown
 ### Authentication
 #### Sign in [status:: done] [release:: MVP]
-#### Remember me [status:: done] [release:: MVP]
 #### SSO [status:: not-started] [release:: Beta]
-#### SAML [status:: not-started] [release:: GA]
 ```
 
-This is more explicit than positional separators — each story carries its own
-release assignment regardless of order in the file.
+### Release identifiers
+
+If a release has a long display name, add an `[id:: short-name]` field to the
+release heading. Stories then use the short id instead of the full name.
+storymap will warn if a release name contains spaces and has no `[id::]`.
+
+```markdown
+# Releases
+## Minimum Viable Product [id:: mvp]
+## Private Beta [id:: beta]
+
+# Map
+## User Management
+### Authentication
+#### Sign in [status:: done] [release:: mvp]
+#### SSO [status:: not-started] [release:: beta]
+```
+
+This decouples the display name from the identifier — you can rename the
+release heading freely without updating every story.
 
 ### Story fields
 
 Stories support optional inline fields using `[key:: value]` syntax.
 Fields appear as badges on the rendered story card.
 
 ```markdown
-#### Story name [status:: done] [persona:: Margie the Manager] [deadline:: 2026-03-01] [release:: MVP]
+#### Story name [status:: done] [persona:: Margie the Manager] [deadline:: 2026-03-01] [release:: mvp]
 ```
 
 | Field | Values | Default |
 |---|---|---|
 | `status` | `not-started`, `in-progress`, `done`, `blocked` | `not-started` |
-| `release` | Release name from `# Releases` section | — |
+| `release` | Release name or id from `# Releases` section | — |
 | `persona` | Any string matching a persona name | — |
 | `deadline` | ISO date `YYYY-MM-DD` | — |
 
@@ -125,24 +142,13 @@ is treated as the story description. Descriptions support standard markdown:
 bold, italics, links, lists, and images.
 
 The first paragraph is always visible on the story card. Additional paragraphs
-(separated by a blank line) are shown only in Detail zoom level.
-
-```markdown
-#### Sign in [status:: done] [release:: MVP]
-User can log in with email and password.
-
-**Acceptance criteria:**
-- Given valid credentials, user is redirected to dashboard
-- Given invalid credentials, an error message is shown
-
-![wireframe](./screens/sign-in.png)
-```
+are shown only in Detail zoom level.
 
 ### Images
 
-Images in story descriptions and persona descriptions are embedded as base64
-data URIs in the output HTML, making the file fully self-contained. Paths are
-resolved relative to the source `.md` file. Remote URLs are left as-is.
+Images in story and persona descriptions are embedded as base64 data URIs in
+the output HTML, making the file fully self-contained. Paths are resolved
+relative to the source `.md` file. Remote URLs are left as-is.
 
 ## Interactive HTML features
 
@@ -151,15 +157,14 @@ The rendered HTML includes controls for navigating large maps:
 **Zoom levels** — three buttons in the sticky header:
 - **Overview** — story names only, compact layout
 - **Map** — story names, status badges, and first-paragraph descriptions
-- **Detail** — full descriptions and acceptance criteria expanded
+- **Detail** — full descriptions expanded
 
 **Release focus** — a dropdown to highlight one release swimlane and dim
 the rest. Works independently of the zoom level.
 
 **Story Lens** — a toggle that enables click-to-zoom on individual story cards.
-When active, clicking a card expands it to ~40% of the viewport width with full
-details visible. Clicking outside collapses it. Stories in the focused release
-(if any) are the only ones that can be expanded.
+When active, clicking a card expands it to ~40% of the viewport width. Clicking
+outside collapses it.
 
 ## CLI reference
 

SKILL.md

@@ -23,8 +23,8 @@ render them to HTML with `storymap render <file>`.
 Optional description.
 
 # Releases        ← required, defines swimlane labels
-## Release 1
-## Release 2
+## MVP
+## Private Beta [id:: beta]   ← use [id::] when name has spaces
 
 # Personas        ← optional
 ## Persona Name
@@ -33,19 +33,21 @@ Description with markdown.
 # Map             ← required
 ## Activity       ← column group
 ### Task          ← column
-#### Story [status:: done] [persona:: Name] [release:: Release 1] [deadline:: YYYY-MM-DD]
+#### Story [status:: done] [persona:: Name] [release:: MVP] [deadline:: YYYY-MM-DD]
 Optional story description.
 
-#### Story in second swimlane [status:: not-started] [release:: Release 2]
+#### Story in beta [status:: not-started] [release:: beta]
 ```
 
 ## Rules
 
 - `# Releases`, `# Personas`, `# Map` are reserved section names (case-insensitive)
 - Any other `#` heading becomes the document title (first one) or is passed through
 - Map hierarchy is strictly `##` Activity → `###` Task → `####` Story
-- Each story is assigned to a release swimlane via `[release:: Release Name]`
-- The `[release::]` value must exactly match a release name defined in `# Releases`
+- Each story is assigned to a release swimlane via `[release:: value]`
+- If a release has no `[id::]`, stories use the release name exactly
+- If a release has `[id:: slug]`, stories must use the slug — not the display name
+- Add `[id::]` whenever a release name contains spaces; omit it for short names like MVP
 - Stories without a `[release::]` field are parsed but not shown in any swimlane
 - Story names are short labels (a few words); put detail in the description body
 - Always add `[status:: ...]` to every story — it drives the card color in the HTML
@@ -60,6 +62,7 @@ Optional story description.
 4. If the user hasn't specified releases, default to two: `MVP` and `Next`
 5. If the user hasn't specified personas, omit the `# Personas` section
 6. Aim for 3–6 activities, 2–4 tasks per activity, 1–3 stories per task per release
+7. Use `[id::]` on releases with spaces in the name; skip it for short names
 
 ## Example
 
@@ -71,8 +74,8 @@ A simple app for individuals to manage daily tasks.
 ## MVP
 Core task management.
 
-## Beta
-Collaboration features.
+## Private Beta [id:: beta]
+Collaboration features with selected users.
 
 # Personas
 ## Sam the Solo User
@@ -86,14 +89,14 @@ Uses the app daily for personal and work tasks.
 #### Add a task [status:: done] [persona:: Sam the Solo User] [release:: MVP]
 Title and optional due date.
 
-#### Add subtasks [status:: not-started] [release:: Beta]
+#### Add subtasks [status:: not-started] [release:: beta]
 
 ### Complete Tasks
 #### Mark task as done [status:: done] [release:: MVP]
-#### Bulk complete [status:: not-started] [release:: Beta]
+#### Bulk complete [status:: not-started] [release:: beta]
 
 ## Sharing
 ### Collaboration
 #### Share task list [status:: not-started] [release:: MVP]
-#### Assign tasks [status:: not-started] [release:: Beta]
+#### Assign tasks [status:: not-started] [release:: beta]
 ```

SYSTEM_PROMPT.md

@@ -28,15 +28,23 @@ Short description of what this product does and who it's for.
 
 Defines the release swimlanes. Each `##` heading is a release.
 
+For short release names (no spaces), no extra syntax is needed:
 ```markdown
 # Releases
 ## MVP
-Core functionality for the first public launch.
-
 ## Beta
-Invite-only beta with selected users.
 ```
 
+For longer names, add an `[id:: slug]` field. Stories then reference the slug
+instead of the full name — this decouples display name from identifier:
+```markdown
+# Releases
+## Minimum Viable Product [id:: mvp]
+## Private Beta [id:: beta]
+```
+
+storymap will warn if a release name contains spaces and has no `[id::]`.
+
 ### Personas section (optional)
 
 UX personas. Each `##` heading is a persona. Descriptions support full markdown.
@@ -60,22 +68,23 @@ The story map itself. Three levels of hierarchy:
 #### Story      — card in a release swimlane
 ```
 
-Each story is assigned to a release swimlane using the `[release:: name]` field.
-The name must exactly match a release defined in `# Releases`.
-Stories without a `[release::]` field are parsed but not shown in any swimlane.
+Each story is assigned to a release swimlane using `[release:: value]`. The
+value must match the release name exactly (for releases without an id) or the
+release id (for releases with `[id::]`). Stories without `[release::]` are
+parsed but not shown in any swimlane.
 
 ```markdown
 ## User Management
 ### Authentication
-#### Sign in [status:: done] [persona:: Alice the User] [release:: MVP]
+#### Sign in [status:: done] [persona:: Alice the User] [release:: mvp]
 User can log in with email and password.
 
-#### SSO login [status:: in-progress] [release:: Beta]
+#### SSO login [status:: in-progress] [release:: beta]
 Support Google and Microsoft OAuth.
 
 ### Profile
-#### Edit profile [status:: done] [release:: MVP]
-#### Upload avatar [status:: not-started] [release:: Beta]
+#### Edit profile [status:: done] [release:: mvp]
+#### Upload avatar [status:: not-started] [release:: beta]
 ```
 
 ### Story fields
@@ -86,7 +95,7 @@ Fields appear as badges on the rendered card.
 | Field | Values |
 |---|---|
 | `status` | `not-started`, `in-progress`, `done`, `blocked` |
-| `release` | Release name from `# Releases` section |
+| `release` | Release name or id from `# Releases` section |
 | `persona` | Any string matching a persona name |
 | `deadline` | ISO date `YYYY-MM-DD` |
 
@@ -96,7 +105,8 @@ Any other `[key:: value]` field is accepted and rendered as a badge.
 
 - Every task must have at least one story
 - Every activity must have at least one task
-- Every story must have a `[release:: name]` field matching a defined release
+- Every story should have a `[release::]` field — stories without one are invisible in the map
+- Use `[id::]` on any release whose name contains spaces; omit it for short names like MVP
 - Story names should be short (a few words) — put detail in the description
 - Use the `status` field on every story so the map is readable at a glance
 
@@ -110,7 +120,7 @@ A simple app for individuals to manage daily tasks.
 ## MVP
 Core task management — create, complete, delete.
 
-## Beta
+## Private Beta [id:: beta]
 Collaboration and sharing features.
 
 # Personas
@@ -124,16 +134,16 @@ Uses the app daily to manage personal and work tasks.
 #### Add a task [status:: done] [persona:: Sam the Solo User] [release:: MVP]
 User can create a task with a title and optional due date.
 
-#### Add subtasks [status:: not-started] [release:: Beta]
+#### Add subtasks [status:: not-started] [release:: beta]
 Break tasks into smaller steps.
 
 ### Complete Tasks
 #### Mark task as done [status:: done] [release:: MVP]
-#### Bulk complete [status:: not-started] [release:: Beta]
+#### Bulk complete [status:: not-started] [release:: beta]
 Select multiple tasks and mark them all done.
 
 ## Sharing
 ### Collaboration
 #### Share task list [status:: not-started] [deadline:: 2026-09-01] [release:: MVP]
-#### Assign tasks to others [status:: not-started] [release:: Beta]
+#### Assign tasks to others [status:: not-started] [release:: beta]
 ```

storymap/parser.py

@@ -229,6 +229,12 @@ def _warn_unmatched_releases(doc: StorymapDocument) -> None:
                         f"Story '{story.name}': release '{r}' not found in "
                         "Releases section — story will not appear in any swimlane."
                     )
+    for release in doc.releases:
+        if release.id is None and " " in release.name:
+            doc.warnings.append(
+                f"Release '{release.name}' has spaces in its name and no [id::] field. "
+                "Consider adding [id:: short-name] to avoid issues when renaming."
+            )
 
 
 def _heading_content(tokens: list, heading_open_index: int) -> str:

tests/test_parser.py

@@ -211,6 +211,21 @@ def test_release_id_stripped_from_display_name(self):
         doc = StorymapParser().parse(src)
         assert "[id::" not in doc.releases[0].name
 
+    def test_release_name_with_spaces_and_no_id_warns(self):
+        src = "# Releases\n## My Long Release\n\n# Map\n## A\n### T\n#### S\n"
+        doc = StorymapParser().parse(src)
+        assert any("My Long Release" in w and "id::" in w for w in doc.warnings)
+
+    def test_release_name_with_spaces_and_id_does_not_warn(self):
+        src = "# Releases\n## My Long Release [id:: mlr]\n\n# Map\n## A\n### T\n#### S\n"
+        doc = StorymapParser().parse(src)
+        assert not any("id::" in w for w in doc.warnings)
+
+    def test_release_name_without_spaces_does_not_warn(self):
+        src = "# Releases\n## MVP\n\n# Map\n## A\n### T\n#### S\n"
+        doc = StorymapParser().parse(src)
+        assert doc.warnings == []
+
     def test_release_description_with_markdown(self):
         src = (
             "# Releases\n"