getMilestonePhaseFilter: greedy custom-ID regex excludes every letter-named phase directory, silently fabricating milestone counts

[bmv002]

Summary

getMilestonePhaseFilter's custom-ID branch in src/roadmap-parser.cts uses a greedy capture that swallows the whole phase-directory name. For any project whose phase directories are letter-named (A-tool-output-contract), every such directory falls out of the milestone, and the milestone progress/plan counts are then computed over whatever numeric directory happens to survive.

The number is not an error — it is well-formed, plausible, and at a phase boundary sometimes even correct. That is what makes it hard to notice. In one project it recurred 26 times across eight phases before anyone checked it against the tree.

The line

src/roadmap-parser.cts:1035

const customMatch = dirName.match(/^([A-Za-z][A-Za-z0-9]*(?:-[A-Za-z0-9]+)*)/);
if (customMatch && normalized.has(customMatch[1].toLowerCase())) return true;

The regex exists to turn PROJ-42-description into PROJ-42. But (?:-[A-Za-z0-9]+)* keeps consuming hyphenated segments, so on A-tool-output-contract it captures A-tool-output-contract, not A. The set membership test then fails and the directory is excluded.

The numeric branch above it is unaffected, which is why this only shows up on letter/custom-ID phase IDs.

Reproduction

Measured against open-gsd/gsd-core @ next, by extracting the real bytes of isDirInMilestone + normalizePhaseIdSegments out of src/roadmap-parser.cts and stripProjectCodePrefix out of src/phase-id.cts and running a real 13-phase tree through them (ROADMAP.md declares Phase 00: and Phase A: … Phase L:; .planning/phases/ holds the matching 13 directories):

  IN   00-inventory-approval-gate
  OUT  A-tool-output-contract
  OUT  B-evidence-artifact-contract
  OUT  C-attention-triage
  OUT  D-async-runner-hardening
  OUT  E-persona-driven-adversarial-e2e
  OUT  F-measurement-bench
  OUT  G-memory-skill-hygiene
  OUT  H-evidence-schema-enum-closure
  OUT  I-runner-fail-open-webhook-debt
  OUT  J-artifact-format-hygiene
  OUT  K-installed-runtime-fail-open-hotfix
  OUT  L-framework-distribution

RESULT (gsd-core HEAD): 1 of 13 phase dirs in-milestone
TRUE totals across all 13 dirs : 89/89
What the filter yields         : 5/5

5/5 is 00-inventory-approval-gate's own counts. The tool reports 5/5 = 100% for a tree holding 89 PLAN.md and 89 SUMMARY.md across 13 phase directories.

Minimal check, no harness needed:

> 'A-tool-output-contract'.match(/^([A-Za-z][A-Za-z0-9]*(?:-[A-Za-z0-9]+)*)/)[1]
'A-tool-output-contract'      // expected 'A'

Why letter-named phases are not an exotic input

They are GSD's own convention. Phase A: … Phase L: headings in ROADMAP.md are produced by GSD's normal roadmap flow, and docs/adr/612-bracket-phase-id-convention.md treats non-numeric phase IDs as first-class. Any project that uses them gets silently wrong milestone progress.

Suggested fix

Replace the capture with a segment-boundary membership test: a directory belongs if its lowercased name equals a declared phase ID, or begins with that ID followed by -.

const lower = dirName.toLowerCase();
for (const id of idsLongestFirst) {
  if (lower === id || lower.startsWith(id + '-')) return true;
}

Two things worth preserving in whatever shape you pick:

1. Try IDs longest-first, so a short ID cannot shadow a longer one (A must not win over A-1 on A-1-foo).
2. Do not use a bare startsWith — ALPHA-x must not match phase A. That would trade this bug for a fail-open in the other direction, and it deserves its own test.

PROJ-42-description → PROJ-42 still matches, which is the case the original capture existed to serve.

Scope of this report — what I ran vs. what I only read

• Reproduced by execution against next HEAD: the filter defect above.
• Read, not executed: syncStateFrontmatter (src/state.cts:1868) rebuilds frontmatter from the parsed object returned by buildStateFrontmatter, and YAML comments are not part of that object, so full-line # comments in .planning/STATE.md's frontmatter are dropped on every write. I did not build an end-to-end repro for this one, so treat it as an observation rather than a confirmed report — happy to open it separately with a proper repro if useful.
• Explicitly NOT reported: the /^(Progress:\s*).*/im pattern whose \s* spans a newline. That one is already fixed at HEAD (src/state.cts:790-791 now uses [ \t]* / [^\r\n]*). Noting it so this report isn't read as broader than it is.

Found while hardening a downstream project against exactly this class of defect — a tool asserting a result it did not compute. Happy to send a PR with the fix and tests if you'd like.

[trek-e]

This was generated by AI during triage.

Diagnosis

Reproduced: yes — ran the exact production regex from isDirInMilestone against A-tool-output-contract; it captures the entire directory name instead of A, confirming the greedy-capture defect. Also confirmed the bug is broader than letter IDs alone: PROJ-42-description does not resolve to PROJ-42 under the current code either — any custom-ID directory with a descriptive hyphenated suffix hits the same failure, since letter/ticket IDs simply never match the numeric branch first and always fall into the broken custom-ID branch.
Root cause: the custom-ID branch's capture group (?:-[A-Za-z0-9]+)* is unbounded/greedy, so it consumes every hyphenated segment of the directory name rather than stopping at the ID boundary. The subsequent set-membership check then fails for almost any directory with a descriptive suffix, silently excluding it from the milestone with no error or warning — in isDirInMilestone (nested inside getMilestonePhaseFilter).
Introduced by: a4da21652 (2026-03-17, "feat: support ticket-based phase identifiers for team workflows #1019") — the commit that added the custom-ID branch in the first place. Unchanged (byte-identical regex) across a later .cjs→.cts migration and a file-extraction refactor; ~5 months old, long-standing.
Blast radius: HIGH (Memtrace get_impact, 44 affected symbols across 14 files, 5 command-routing processes). This filter is the sole source of truth for "which phase directories belong to the active milestone," feeding milestone/phase progress percentages, STATE.md frontmatter progress blocks, milestone-completion eligibility, workstream inventory status, and UAT/health audit denominators — all silently wrong for any project using letter or ticket-style phase IDs, with no error surfaced.
Coupled (must not miss): the fallback branch that calls stripProjectCodePrefix (project-code-prefixed numeric IDs, e.g. HQ-01-...) is a separate, currently-correct code path — a fix to the custom-ID branch must not touch or shadow it.
Regression test: given a ROADMAP declaring Phase A: / Phase B: and a phase-directory tree containing A-tool-output-contract/ and B-evidence-artifact-contract/, both directories must be classified as in-milestone and their plan/summary counts must both be included in the milestone total — not just whichever directory happens to have no descriptive suffix.

Agent Brief

Category: bug
Summary: Custom (letter/ticket-style) phase-ID matching against milestone phase directories uses an unbounded greedy regex capture, so any phase directory with a descriptive suffix beyond its bare ID is silently excluded from milestone membership.
Current behavior: A phase directory named <ID>-<descriptive-words> (the standard GSD slug shape) is excluded from the active milestone whenever <ID> is a non-numeric (letter or ticket-style) phase identifier, because the ID-extraction match consumes the entire directory name instead of stopping at the ID boundary. The resulting milestone progress/plan counts silently omit that phase entirely — no error, no warning, just a smaller-but-plausible number.
Desired behavior: Any phase directory whose name equals a declared phase ID, or begins with that ID followed by a separator, is correctly recognized as belonging to the milestone — regardless of how many additional descriptive words follow the ID in the directory name.
Key interfaces: the milestone phase-membership filter used by milestone/phase progress reporting, milestone-completion eligibility checks, workstream status inspection, and UAT/health audit counts.
Acceptance criteria:

• A directory A-tool-output-contract is recognized as belonging to phase A when A is declared in the milestone.
• A directory PROJ-42-description is recognized as belonging to phase PROJ-42 when PROJ-42 is declared (the case the original matching logic was meant to serve).
• A directory ALPHA-x is NOT recognized as belonging to phase A — a bare prefix match is not sufficient; the character following the matched ID must be a genuine separator, not just any continuation.
• When both A and A-1 are declared as phase IDs, a directory A-1-foo resolves to A-1, not to A — the longer, more specific ID must not be shadowed by a shorter one that happens to be a prefix of it.
• A full milestone/phase progress count computed over a tree with multiple non-numeric-ID phase directories reflects the true total across all of them, not just the directories that happen to have no descriptive suffix.
  Out of scope: this fix touches only custom/non-numeric phase-ID directory matching. It must not change the numeric phase-ID matching branch, the stripProjectCodePrefix project-code fallback branch, or STATE.md frontmatter comment handling — a separate, independently-confirmed defect (full-line # comments in STATE.md frontmatter are dropped on every write) that is explicitly not part of this fix and is tracked separately.