Support ticket-based phase identifiers for team/async workflows

[denagyantal]

Problem

When multiple teammates use GSD on the same repo, sequential phase numbering causes collisions. Phase numbers are auto-incremented from ROADMAP.md (maxPhase + 1), so if two people create phases concurrently, they get the same number.

In our case, 5 engineers share a GSD-managed monorepo. We constantly collide on the next phase number.

Proposed Solution

Allow non-numeric phase identifiers — specifically, arbitrary string IDs such as ticket/issue IDs (e.g., PROJ-42, AUTH-101, FEAT-7) as phase identifiers.

Why arbitrary string IDs work:

• Already unique — no coordination needed
• Maps to existing workflow (Jira, Linear, GitHub Issues, or any custom scheme)
• Phase ordering already comes from depends_on in plan frontmatter, not from numbering

Example:

.planning/phases/
  PROJ-42-user-authentication/
  AUTH-101-session-management/
  FEAT-7-dashboard-redesign/

ROADMAP.md:

### Phase PROJ-42: User Authentication
**Depends on:** FEAT-7

What would need to change

The sequential integer assumption is hardcoded in several places:

• core.cjs: normalizePhaseName() only matches ^\d+, comparePhaseNum() only compares integers, searchPhaseInDir() regex assumes numeric prefix
• phase.cjs: cmdPhaseAdd() does maxPhase + 1, cmdPhaseInsert() assumes numeric base
• roadmap.cjs: Phase header regex only matches Phase \d+:
• verify.cjs: Health check warns on "gap in phase numbering" and expects NN-name format
• commands.cjs: dir.split('-')[0] assumes single-segment numeric prefix

Possible config option

A phase_naming setting in config.json:

{
  "phase_naming": "sequential"  // default, current behavior
  // or
  "phase_naming": "custom"      // accept any arbitrary string ID via --id flag
}

With "custom" mode:

• gsd-tools phase add --id PROJ-42 "User Authentication"
• Skip auto-increment logic
• Relax health check warnings about sequential numbering gaps

Environment

• 5-person team sharing one GSD repo
• Each person works on separate feature branches but phases land on main

🤖 Generated with Claude Code

[MarcinWArdentCode]

Please, please, make it happen.

For our company this is the major blocker from seeing a wider GSD adoption.

[trek-e]

Investigation

The sequential integer assumption is deeply embedded across the codebase. Based on the issue's own analysis, these locations would need changes:

• core.cjs: normalizePhaseName(), comparePhaseNum(), searchPhaseInDir() — all assume numeric prefix
• phase.cjs: cmdPhaseAdd() (maxPhase + 1), cmdPhaseInsert() — numeric auto-increment
• roadmap.cjs: Phase header regex (Phase \d+:)
• verify.cjs: Health check warns on numbering gaps
• commands.cjs: dir.split('-')[0] assumes single numeric prefix

Scope assessment: This is a significant architectural change that touches the core phase identity system. The phase_naming: "custom" config approach proposed in the issue is sound, but implementing it requires:

1. Adding a string-based phase comparison function alongside the numeric one
2. Making all phase regexes configurable (numeric vs arbitrary string)
3. Updating directory scanning to handle non-numeric prefixes like PROJ-42-user-auth/
4. Relaxing health check validations in custom mode
5. Updating ROADMAP.md parsing to accept ### Phase PROJ-42: headers

Workaround for teams today:

• Use a numeric prefix that encodes the ticket: 42-user-authentication/ (ticket 42)
• Or use phase descriptions that reference tickets: Phase 5: PROJ-42 User Authentication
• The depends_on field in plan frontmatter already handles ordering

This would be a good candidate for a dedicated milestone or a community contribution with deep codebase knowledge.

[trek-e]

PR #1134 implements ticket-based phase identifiers. Set "phase_naming": "custom" in config.json and use phase add --id PROJ-42 "description". All existing tests pass, fully backward compatible.

[trek-e]

This issue is addressed by PR #1134. The fix is ready for review and merge.

[trek-e]

Closing — addressed by PR #1134.