Skip to content

proposal: allow changes to be nested under a namespace folder #1917

Description

@clay-good

Follow-up to #1846 / #1849.

Ask: Let changes be grouped under a namespace folder the way specs already can (changes/mobile/refresh-token/ next to specs/mobile/tutorial-videos/), so one shared store can keep each product's changes together.

Today: #1849 makes a nested change fail loudly instead of being silently mishandled. Flat names like mobile-refresh-token are a temporary workaround.

Proposed design

Treat a change id as a path, just like a spec capability path.

Area Behavior
Id grammar One or more kebab-case segments joined by / (mobile/refresh-token). Each segment passes the existing isKebabId check. No .., leading/trailing /, or empty segments. Flat ids stay valid, so nothing existing breaks.
What counts as a change A directory that holds .openspec.yaml (which openspec new change always writes). Any other folder on the way down is a namespace. This replaces the #1849 heuristic with one rule.
Commands new, list, show, status, instructions, validate, and archive all accept the full path id. list groups changes by namespace.
Archive Keeps the namespace: changes/archive/mobile/2026-09-18-refresh-token/. It moves only the change directory, never a namespace folder or sibling changes.
Completion Suggests full path ids.

Why not the alternatives: a --directory flag splits one piece of information across two inputs and has to be repeated on every command. Keeping flat names forever leaves changes/ and specs/ organized differently for no reason.

Guardrail: archive must never move or drop an unfinished nested change (the #1846 data-loss case), and there should be a regression test for that.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    design-reviewNeeds product/design decision

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions