fix(cli): let --change find change names that exist on disk

[clay-good]

Fixes #1308.

What was wrong

Any command taking --change (status, instructions <artifact>, instructions apply) rejected digit-leading change names at parse time:

$ openspec status --change 2026-07-04-voice-copilot-v1
✖ Error: Invalid change name '2026-07-04-voice-copilot-v1': Change name must start with a letter

Meanwhile list, validate, and archive all handled the same change fine, so a change could live its whole lifecycle while being unaddressable by --change. Repos with a date-prefixed naming convention (which the archive flow itself produces) couldn't use the status/instructions workflow at all.

The cause: validateChangeExists() reused validateChangeName() — the creation-time kebab-case rule — as its path-traversal guard, so the lookup path enforced a naming convention on directories that already exist.

How it was fixed

Lookup and creation are now separate rules, matching how the rest of the CLI behaves:

• Lookup (--change) accepts any directory name that openspec list could return, and only rejects unsafe names: path separators, ./.., null bytes, and hidden (dot-leading) entries.
• Creation (openspec new change) still enforces kebab-case via validateChangeName() — this PR takes no position on Support numbered change names (NNNNN-slug) for sequencing #1169 (numbered names at creation).

One small function in src/commands/workflow/shared.ts; no other call sites touched.

Replication / proof

Before (repro from the issue, real output):

$ openspec status --change 2026-07-04-voice-copilot-v1
✖ Error: Invalid change name '2026-07-04-voice-copilot-v1': Change name must start with a letter

After:

$ openspec status --change 2026-07-04-voice-copilot-v1
Change: 2026-07-04-voice-copilot-v1
Schema: spec-driven
Progress: 1/4 artifacts complete
...
$ openspec status --change ../foo
✖ Error: Invalid change name '../foo': Change name cannot contain path separators

Tests: new cases for digit-leading names on status and instructions, plus a hidden-name rejection; the existing traversal tests (../foo, /etc/passwd, foo/bar) pass unchanged. Full suite: 1,861 passed (the 17 zsh-installer failures are the known local-environment ones).

Notes

• Lookup now also accepts other on-disk names the old rule rejected (uppercase, underscores) — intentional, since list/archive already resolve those directories.
• Includes a patch changeset.

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • The --change option now accepts any safe existing change name on disk, including date- or digit-prefixed names.
  • Change lookup resolution is now consistent with other change-related commands (e.g., list/validate/archive).

• Bug Fixes

  • Unsafe names (hidden entries, path separators, relative segments like ./.., and null characters) are still rejected.
  • The reserved name archive is rejected when provided via --change.

• Tests

  • Expanded CLI coverage for status and instructions change-name validation and acceptance.

• Documentation

  • Updated behavior notes for the --change option accordingly.

[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

Run ID: ae68c097-8c13-4011-a116-c33c2e06525a

📥 Commits

Reviewing files that changed from the base of the PR and between 990cf72 and 2709f60.

📒 Files selected for processing (2)

• src/commands/workflow/shared.ts
• test/commands/artifact-workflow.test.ts

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

• src/commands/workflow/shared.ts
• test/commands/artifact-workflow.test.ts

---

📝 Walkthrough

Walkthrough

The --change workflow now separates lookup-name validation from creation-name validation, allowing existing digit-leading or date-prefixed changes while rejecting unsafe names. Status and instructions tests cover these cases, and the changeset documents the behavior.

Changes

Change Lookup

Layer / File(s)	Summary
Lookup safety validation src/commands/workflow/shared.ts	Adds dedicated safety checks for lookup names and updates validateChangeExists to report lookup-specific validation errors.
CLI coverage and behavior notes test/commands/artifact-workflow.test.ts, .changeset/change-lookup-accepts-existing-names.md	Tests accepted digit-leading names and rejected hidden or reserved names for status and instructions, and documents the lookup rules.

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

Sequence Diagram(s)

sequenceDiagram
  participant WorkflowCommand
  participant validateChangeExists
  participant ChangeDirectory
  WorkflowCommand->>validateChangeExists: provide --change name
  validateChangeExists->>validateChangeExists: validate lookup safety
  validateChangeExists->>ChangeDirectory: resolve existing change directory
  ChangeDirectory-->>validateChangeExists: return directory result

Loading

Possibly related issues

• Support numbered change names (NNNNN-slug) for sequencing #1169 — Concerns allowing digit-prefixed existing change names during lookup.
• feat(validation): allow numeric-prefixed change names for ordered/tiered workflows #850 — Addresses numeric-prefixed change-name handling and creation validation.

Possibly related PRs

• Fission-AI/OpenSpec#759 — Modifies change lookup behavior in the same workflow module.
• Fission-AI/OpenSpec#1367 — Provides related change-path and domain validation used by workflow lookup.

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 summarizes the main change: letting --change resolve existing on-disk change names.
Linked Issues check	✅ Passed	The PR matches #1308 by allowing digit-leading existing change names for --change in status/instructions while preserving safety checks.
Out of Scope Changes check	✅ Passed	The changes are focused on change-name lookup, related tests, and a note update; no unrelated scope is evident.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

✨ 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/change-lookup-accepts-existing-names

Warning

There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 ESLint

If the error stems from missing dependencies, add them to the package.json file. For unrecoverable errors (e.g., due to private dependencies), disable the tool in the CodeRabbit configuration.

ESLint install timed out. The project may have too many dependencies for the sandbox.

---

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 `@src/commands/workflow/shared.ts`:
- Around line 136-160: Update validateChangeLookupName to reject the reserved
change name "archive", matching the exclusion applied by getAvailableChanges
before returning undefined for otherwise safe names.

🪄 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

Run ID: 5486705e-83a4-4323-8ac1-a95959652629

📥 Commits

Reviewing files that changed from the base of the PR and between 0a99f41 and 990cf72.

📒 Files selected for processing (3)

• .changeset/change-lookup-accepts-existing-names.md
• src/commands/workflow/shared.ts
• test/commands/artifact-workflow.test.ts

[alfred-openspec]

Reviewed the diff, linked issue, surrounding workflow/apply paths, CI, and focused local tests. Looks good to merge.