fix(validate): allow numeric-prefixed change names

[clay-good]

Status: LGTM — surgical, backward-compatible, all 2,238 tests pass.

What was wrong

openspec new change 100-add-feature (or 00001-add-auth) failed with:

✖ Error: Change name must start with a letter

validateChangeName required change names to begin with a letter. But the rest of OpenSpec already treats a leading digit as legitimate:

• The canonical kebab-id grammar in src/core/id.ts — shared by store ids, workset names, and change metadata ids — allows a leading digit (/^[a-z0-9]+(?:-[a-z0-9]+)*$/).
• Archive explicitly supports YYYY-MM-DD--prefixed change names as "a common authoring convention" and avoids double-dating them (archive prepends today's date without detecting an existing date prefix (name gets double-dated) #1309).

So OpenSpec shipped archive support for a naming convention its own creation gate refused to create. Users wanting ordering/tiering (100-audit, 200-implement, 00001-add-auth) had to fork the CLI or create directories by hand.

How it was fixed

validateChangeName now reuses the canonical isKebabId grammar instead of its own stricter regex, and the now-unreachable "must start with a letter" branch is removed. The tailored error messages for every other case (uppercase, spaces, underscores, leading/trailing hyphens, consecutive hyphens, invalid characters) are unchanged.

One import + one predicate swap + dead-branch removal — no new options, no schema/config surface, no workflow changes.

Proof it works

Before, 100-add-feature errored. After (real CLI output):

$ openspec new change 100-add-feature
Created change '100-add-feature' at openspec/changes/100-add-feature/

$ openspec new change 00001-add-auth
Created change '00001-add-auth' at openspec/changes/00001-add-auth/

# still correctly rejected:
$ openspec new change add--auth   → ✖ Change name cannot contain consecutive hyphens
$ openspec new change Add-Auth    → ✖ Change name must be lowercase (use kebab-case)

Backward compatibility is guaranteed: [a-z] ⊂ [a-z0-9], so every previously valid name still validates. Added tests cover 100-add-feature, 00001-add-auth, 101-01-fix-auth, and an end-to-end createChange for a numeric-prefixed directory. Full suite: 2,238 passing.

Notes

• Auto-numbering (the optional --number / --auto-number flag suggested in feat(validation): allow numeric-prefixed change names for ordered/tiered workflows #850 and Support numbered change names (NNNNN-slug) for sequencing #1169) is intentionally out of scope — this PR only removes the validation barrier so wrapper tools and users can name changes as they choose. A dedicated flag can follow separately.
• Open PR feat(validation): allow dots in change names as valid separators #842 (allow dots in change names) touches the same function; the two are orthogonal and will resolve with a trivial merge.

Closes #850
Closes #1169

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • openspec new change now accepts change names that begin with digits (including zero-padded and digit-only formats).

• Tests

  • Expanded validation and parsing tests for numeric-prefixed naming patterns.
  • Added coverage to ensure numeric-prefixed names create the expected change directory.

• Documentation

  • Updated CLI documentation to remove the “must start with a lowercase letter” restriction and add new examples.

• Bug Fixes

  • Improved change-name validation to follow the shared kebab-case grammar and provide consistent diagnostics for invalid formats.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: c8d63bd9-8866-406c-b6f1-aae6f8f18845

📥 Commits

Reviewing files that changed from the base of the PR and between fcc522b and 3e84d5b.

📒 Files selected for processing (1)

• test/utils/change-utils.test.ts

🚧 Files skipped from review as they are similar to previous changes (1)

• test/utils/change-utils.test.ts

---

📝 Walkthrough

Walkthrough

validateChangeName now uses OpenSpec’s shared isKebabId grammar, allowing valid digit-leading names. Tests cover numeric-prefixed validation and creation of matching change directories, while CLI documentation and release metadata describe the updated rules.

Changes

Numeric-prefixed change names

Layer / File(s)	Summary
Adopt shared change-name grammar src/utils/change-utils.ts	validateChangeName uses isKebabId, documents the expanded rules, and removes the digit-specific rejection.
Test numeric-prefixed names test/utils/change-utils.test.ts	Validation tests cover numeric-prefixed and digit-only names, while createChange verifies the matching directory is created.
Document accepted naming rules docs/cli.md, .changeset/allow-numeric-prefixed-change-names.md	CLI guidance and release metadata describe numeric-prefixed names and retained invalid-name restrictions.

Estimated code review effort: 2 (Simple) | ~10 minutes

Possibly related PRs

• Fission-AI/OpenSpec#408: Both changes modify validateChangeName and accepted change-name grammar.
• Fission-AI/OpenSpec#1375: Both changes address digit-leading change-name validation in CLI workflows.

Suggested reviewers: tabishb

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly matches the main change: allowing numeric-prefixed change names.
Linked Issues check	✅ Passed	The code and tests implement the requested numeric-prefix validation change while preserving existing valid names.
Out of Scope Changes check	✅ Passed	The docs and changeset support the feature and no unrelated changes are evident.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/allow-numeric-prefixed-change-names

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@test/utils/change-utils.test.ts`:
- Around line 44-47: Update the test case around validateChangeName to use an
all-numeric-and-hyphen fixture such as 101-01, preserving the expected valid
result; ensure the test title accurately describes that coverage.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 797bd081-bc7a-4e37-888a-e1dd97f34d48

📥 Commits

Reviewing files that changed from the base of the PR and between 26f009d and 46f794d.

📒 Files selected for processing (2)

• src/utils/change-utils.ts
• test/utils/change-utils.test.ts

[cloudflare-workers-and-pages]

Deploying openspec-docs with    Cloudflare Pages

Latest commit:	37f7217
Status:	✅  Deploy successful!
Preview URL:	https://fc186505.openspec-docs.pages.dev
Branch Preview URL:	https://fix-allow-numeric-prefixed-c.openspec-docs.pages.dev

View logs

[clay-good]

Merge-coordination note for whoever lands this (no action needed on the code itself):

Two open PRs edit the same validateChangeName:

• feat(validation): allow dots in change names as valid separators #842 (allow dots in change names) touches the same regex line. Resolution is a deliberate superset — keep this PR's isKebabId grammar and re-add feat(validation): allow dots in change names as valid separators #842's dot support + consecutive-dot guard. Taking either side wholesale drops the other's behavior.
• feat: support multi-level change domains and sibling archives #1367 (multi-level change domains) relocates validateChangeName into a new change-path.ts and re-introduces the old /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/ + "must start with a letter" branch. If feat: support multi-level change domains and sibling archives #1367 lands first, please re-apply the one-line swap (isKebabId(name), drop the /^[0-9]/ branch) in change-path.ts — otherwise this numeric-prefix fix is silently reverted. The 100-add-feature / 00001-add-auth / 100 tests move with the function and are the tripwire.

Simplest path is to merge this small PR first.

[alfred-openspec]

Clean, backward-compatible validator alignment. I verified numeric-prefixed changes through create, status, list, and archive, and the full 2,239-test suite passes at head 37f7217.