fix(#2528): resolve digit-leading phase directories by bare number (#2559)

* fix(#2528): resolve digit-slug phase dirs by bare number — tokenizer rewind, shared bare-integer fallback, resolution-path parity gate extractPhaseToken welded 2-digit slug words onto the phase token (phase 10 named "24/7 Autonomy" -> dir 10-24-7 -> token 10-24), making digit-prefixed phase names unresolvable by bare number across every phase verb. - phase-id: continuation segments must be the PURE 2-digit zero-padded form the write side emits; a 1-digit terminator rewinds the absorbed run (10-24-7 -> 10) while >=2-digit terminators keep the locked #2232 round-trip (14-06-2026-photos -> 14-06). - phase-id: new matchPhaseDirs owner — primary exact-token match plus a bare-integer leading-digit-run fallback for shapes the tokenizer cannot rewind (05-80-20-cleanup); collisions stay #2237-loud. - locator/find-phase/phase-plan-index all delegate selection to the owner; plan-index gains the previously missing multi-match guard. - tests: #2528 unit + fast-check metamorphic blocks; new 9-scenario resolution-path parity gate across all three paths. Fixes #2528 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * chore(#2528): add changeset for PR #2559 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * fix(#2528): align validation token grammar * fix: address phase token review * fix: restore phase grammar parity for numeric slugs * docs: document digit-leading phase resolution * docs: clarify ambiguous phase resolution behavior * docs: register canonical phase directory selectors * fix: align prefixed deep phase token parsing * fix(#2528): route the fourth resolution site through matchPhaseDirs Review BLOCKER. smart-entry.cts::detectVerifyFailed resolved the current phase's directory with its own `.find(phaseTokenMatches)` and never reached the shared selection, so the bare-integer-fallback family the issue names — `05-80-20-cleanup`, `30-12-factor-refactor` — resolved nowhere. The miss is silent by construction: an unresolved phase reports "not failed", which is byte-identical to a healthy one, so a failed verification simply never surfaced in /gsd or /gsd:progress. `entries` is already sorted and matchPhaseDirs filters without reordering, so matches[0] reproduces the previous selection exactly wherever the old code resolved at all. Wiring it into phase-resolution-parity.test.cjs as a fourth path then exposed a second, older defect in the same function: phaseTokenFromDirName shape-probed the UNSTRIPPED token, so a project-code-prefixed directory (`MEM-05-…`, tokenizing to `MEM-05-80-20`) failed the leading-digit test and was dropped before any resolution ran — every phase in a project-coded plan was invisible to this check. The probe now runs on the stripped token; the returned value is unchanged, so the comparePhaseNum sort is untouched. Path 4 has no JSON surface to compare, so the gate observes selection indirectly: plant the failing artifact in exactly one directory and a passing one everywhere else, then read the boolean. Reverting either fix turns 5 of the 10 corpus scenarios red. * refactor(#2528): collapse the duplicated extractCanonicalPlanId Review MAJOR. The function existed as two independent, byte-identical copies — src/core-utils.cts and src/phase.cts — and this PR had to patch BOTH with the same single-digit-slug rewind rule. That is the generative fix divergence CLAUDE.md names, and only the core-utils copy was under test, so a future one-sided patch would have silently split plan-id canonicalization between the plan listing and everything else. Removed rather than parity-tested: core-utils was already the leaf owner and already exported it, and phase.cts already imported that module, so there is no second surface left for a parity test to police. * test(#2528): pin matchPhaseDirs at the digit-width boundaries Review MAJOR. The bare-integer fallback's correctness rests entirely on capturing each directory's whole leading digit run before the zero-strip compare; a regex that stopped short would turn every query into a prefix match, and "1" would claim 10, 100, and 12 alike. The existing coverage was example-based and never touched that boundary. Adds the explicit 9/10 and 1/10/100 cases — including the forms where only the wider directories exist, so an exact-width neighbour cannot satisfy the assertion — plus a fast-check property over arbitrary distinct leading runs. The property is stated as an invariant on the result (every returned directory's leading run IS the query) rather than an expected list, so it covers primary and fallback matches alike and cannot be satisfied by reimplementing the selection in the test. Both fail when the fallback regex is degraded to a prefix match. * fix(#2528): route the remaining eight consumers through matchPhaseDirs phaseTokenMatches had eight consumers left that each rebuilt the directory selection around it by hand: phases-list, next-decimal, phase-remove, the W021 milestone-consistency check, schema-drift, the init-manager overview, milestone-complete's disk check, and roadmap analyze. Every one of them reproduced the reported symptom in full after the tokenizer was fixed. None of them derives a displayed phase number from the matched directory, so none needs phaseNumberForMatch; the change at each site is the selection and nothing else. matchPhaseDirs filters without reordering, so matches[0] reproduces the prior .find() choice wherever the old code resolved at all. phaseTokenMatches now has no call sites outside phase-id.cts. It stays exported as the primitive matchPhaseDirs is built from and as a pinned canonical surface, but no consumer reaches past the owner to it. * test(#2528): extend the parity gate to the migrated consumers Each of the eight is observed through the surface a user sees, not through the matcher, with a no-directory control so the assertions cannot be satisfied by a consumer that resolves unconditionally. init-manager and roadmap-analyze are additionally asserted to agree with each other. * refactor(#2528): own the case-flexible phase grammar and the leading-digit-run fragment validate.cts derived its case-flexible regex sources by running `replaceAll('A-Z', 'A-Za-z')` over two constants exported by phase-id.cts. That passes lint-phase-id-drift.cjs — there is no literal copy of the grammar — but it depends on the owner rendering that exact substring. The day phase-id.cts expresses the same class any other way the replaceAll silently no-ops and validate.cts narrows to uppercase-only. The failure mode is a NON-match, so nothing throws and no uppercase-only fixture notices. Both variants are now derived once, beside the sources they widen, and imported. Also names the leading digit run the bare-integer fallback selects on. It was spelled `/^(\d+)(?:-|$)/` where the fallback filters and `/^\d+/` where phaseNumberForMatch reads the number back off the winner; selecting on one run and displaying another would resolve a directory and then label it with a number that never matched it. * fix(#2528): refuse to remove a phase when two directories claim its number cmdPhaseRemove was the only migrated site taking matches[0] with no multi-match guard. Every sibling resolution path returns ambiguous_matches and refuses to choose; this one is the DESTRUCTIVE path, so choosing silently is strictly worse than anywhere else. With 05-80-20-a and 05-90-till-late on disk, `phase remove 5 --force` deleted one of them and renumbered every phase after it — where the base resolved nothing, deleted nothing, and the corpus in tests/phase-resolution-parity.test.cjs already declared that exact input ambiguous. The refusal is emitted before any file is touched and carries both candidates. CONSUMER_SCENARIOS could not express the case — every row is binary, resolving to one directory or to none — so the gate gains a dedicated ambiguous test. It asserts on the filesystem, not only on the reported directory_deleted: a null printed after an rmSync would satisfy every other check. * fix(#2528): pair digit-leading phase directories with their roadmap phase in validate health W006/W007 are the ninth site of this bug class and the one a `phaseTokenMatches` grep could never surface: they resolve roadmap↔disk by intersecting TOKEN SETS, which is a dir→token labelling rather than the query→dir selection matchPhaseDirs owns. On the canonical fixture the label is wrong in both directions at once, so `validate health` reported "Phase 5 in ROADMAP.md but no directory on disk" AND "Phase 05-80-20 exists on disk but not in ROADMAP.md" for the same directory. collectDiskPhases now keeps the directory names behind each token, so W006 can ask the canonical matcher whether a roadmap phase resolves to a real directory, and W007 — which iterates directories and therefore has no query to resolve — gets the inverse mapping it never had: a directory is claimed when some roadmap phase resolves to it. Both checks are additive: the token intersection still decides every shape it already decided, and the resolution can only REMOVE a warning. The regression test carries controls in the other direction — a roadmap phase with no directory must still raise W006, an unclaimed directory must still raise W007 — so it cannot be satisfied by a check that stopped reporting. * docs(#2528): state and pin the directory-side scope of the bare-integer fallback The matchPhaseDirs docblock claimed deep-decomposition lookups were untouched. That is true of the QUERY side only — no non-bare query enters the fallback — but the DIRECTORY side is what changed classification: a bare `5` now reaches a lone `05-01-auth` and resolves it (phase_number "05", phase_name "01-auth") where the base found nothing. The widening is irreducible from directory names alone. `05-01-auth` (sub-phase 5.1) and `30-12-factor-refactor` (phase 30 named "12-Factor Refactor") are the same `NN-NN-<slug>` shape, and the discriminator that would separate them — "is the second segment a valid decimal sub-phase" — accepts `5.1` and `30.12` equally. Any rule strong enough to exclude the first excludes the second, which is the defect #2528 exists to fix. So the tie is broken in favour of resolving, the docblock now says so, and the consequence is bounded where it matters: two such directories are two matches, and every caller (including phase remove) refuses to choose. Pins both directions, since nothing observed the directory side before. * fix(#2528): count surviving phases by identity in phase remove's STATE resync #2640 landed on `next` while this branch was open. Its STATE.md phase-count resync re-derives "which directory was removed" from the query with `phaseTokenMatches`, which is the tenth site of this issue's defect: the bare-integer fallback resolves `05-80-20-cleanup` for query `5`, but the token predicate does not, so the just-deleted directory is counted as still present and the written `Total Phases` is one too high. `targetDir` already IS the directory that was removed, and the block is gated on it being non-null, so identity answers the question exactly — which is also what the comment above the filter already claimed it did. This keeps `phaseTokenMatches` out of `phase.cts` rather than re-importing it to satisfy one call site: the module's public surface should not grow for a question that does not need re-derivation. Pinned in the parity gate with a control on a directory the tokenizer reads correctly, so the assertion is about the digit-leading shape and not about the counting rule changing for everything. * fix(#2528): let the resolution layer own the digit-leading slug family alone The tokenizer rewind this fix carried — pop the last absorbed continuation when the segment that stopped the scan is a bare single digit — reads "10-24-7-autonomy" (phase 10 named "24/7 Autonomy") correctly and silently re-reads "10-24-7-zip" (sub-phase 10.24 named "7-Zip Integration") from "10-24" to "10". The two names are string-identical in shape, so no local signal separates them; the rule traded the reported ambiguity for the symmetric one a level down, on a 15-caller chokepoint whose output also feeds query-less derivations (STATE.md phase counts, W007, the #2562 key surface). A well-formed sub-phase directory became unresolvable by its own id — the very symptom #2528 was filed about. It also bought nothing. The bare-integer fallback in matchPhaseDirs already resolves "10-24-7-autonomy" for query "10" whatever the token is: no primary match, bare query, leading digit run "10". The reported case was covered twice, by two rules, and the two disagreed about the case nobody reported. So the rewind is removed rather than narrowed, in the tokenizer and in the five surfaces kept in lockstep with it (BRACKET_PHASE_TOKEN_SOURCE, PHASE_TOKEN_FROM_DIR_RE, canonicalPlanStem's pair grammar and its collision branch, roadmap-parser's numericRe, extractCanonicalPlanId), together with the SINGLE_DIGIT_RUN_SEGMENT_SOURCE owner constant they shared. Disambiguation now lives only where a QUERY exists to disambiguate against, which is the same bounded mechanism the "05-80-20-cleanup" shape already used. Measured, not argued: over 29800 generated directory names, extractPhaseToken is byte-identical to `next` on every input except the lowercase-continuation class ("01-20a", "05-80-20-25abc") — a rule about the segment itself, not a guess about its neighbour. Both readings now stay reachable by their own ids: matchPhaseDirs(['10-24-7-autonomy'], '10') -> the dir (fallback) matchPhaseDirs(['10-24-7-zip'], '10') -> the dir (fallback) matchPhaseDirs(['10-24-7-zip'], '10-24') -> the dir (primary) * test(#2528): pin the one-continuation boundary the rewind had no coverage for The regressing shape was invisible to the suite by construction, not by luck: the deep-rewind property built its cases from `continuationArb` with `minLength: 2`, so it never exercised the single-continuation case — exactly one genuine sub-phase level before a digit-leading slug — and every hand-written fixture used the ambiguous shape only where "phase-plus-slug" was the intended reading. `continuationArb` is now `minLength: 1` and the property states the invariant instead of the old rule: for any prefix, phase, 1-5 continuations and any one-digit terminator, the token equals the FULL continuation run on both the imperative and the regex surface, and `matchPhaseDirs([dir], token)` returns that dir. That third assertion is the one that catches the class on its own — the old behaviour made a well-formed directory unresolvable by its own id, which is a property, not a fixture. Around it: "10-24-7-zip" and "10-24-3d-printer" now sit beside "10-24-7-autonomy" everywhere the family is pinned, so the two readings can never diverge again; the 24/7 metamorphic property asserts the RESOLUTION result rather than the token (the token is precisely the part no surface may decide); the end-to-end parity corpus gains "a sub-phase with a digit-leading slug resolves by its full id" across all four resolution paths; and the milestone-scoping residual is pinned in three directions rather than left to prose. Mutation: re-inserting the rewind and rebuilding turns 9 tests red, the `minLength: 1` property first, and nothing else. Build success checked separately (build:lib reports 0 `error TS`), so the mutation reached the artifact under test. * test(#2528): pin the #2946 guard against digit-leading phase directories The #2946 fix makes the milestone-complete unstarted-phase guard run unconditionally, so whether it fires now rides entirely on the directory-resolution owner this PR replaces. Two cases, both with STATE.md carrying no `milestone:` field so the #2946 path is the one exercised: - ROADMAP Phase 5, disk `05-80-20-cleanup` → guard must stay silent. RED on next (fail-closed: the guard blocks a legitimate one-way-door operation because phaseTokenMatches resolves neither 05 nor 80 for that directory). - ROADMAP Phase 80, same directory → guard must still fire. Green on both sides; it pins the fail-open direction against a future widening of the matcher. * fix(#3175): stop the injection scanner reading RegExp.exec as code execution The apostrophe fix in 27aa40f6 replaced ["\x27] with a real ["'] class. The old class never contained an apostrophe at all (POSIX bracket expressions do not honour backslash escapes, so it was the set ", \, x, 2, 7), so only exec(" matched. Single-quoted method calls now match for the first time, and RegExp.prototype.exec takes a subject string, not code: any PR touching a file that tests a regex goes red. On next, six files match the scanner's own pattern across 16 method calls. A plain [^[:alnum:]] boundary cannot separate the two forms because . is not alnum, so exec gets [^[:alnum:].] and the command-execution vector moves to a dedicated member-call pattern. Bare exec('rm -rf /'), cp.exec(...) and child_process.exec(...) all still fire. Mutation: reverting the boundary reds 1 test and only it; removing the member-call pattern reds the 2 non-weakening tests and only them. Co-Authored-By: Claude <noreply@anthropic.com> * fix(#2528): keep exec( detection receiver-blind, allowlist the two grammar suites The left boundary [^[:alnum:].] added in 58a7b560 excluded a preceding dot, which dropped every member-position .exec('…') from the scanner. The follow-up receiver pattern only restored three literal spellings (child_process, childProcess, cp), so require('child_process').exec('…') — the most common Node spelling of the vector this pattern exists to catch — became invisible, along with any opaque receiver (conn.exec, shelljs.exec). Revert the pattern to its receiver-blind form and handle the RegExp.prototype .exec false positive where the script already handles this class: per-file ALLOWLIST entries for the two phase-token grammar suites. Mutation-checked — removing the two entries reds exactly those two files and nothing else. The four assertions written around the old patterns are replaced by a table-driven set covering all six spellings, including the three the narrowed pattern silently lost. Co-Authored-By: Claude <noreply@anthropic.com> * docs(#2528): pin the three undeclared grammar edges, correct the ambiguity claim Review round 10 asked for declaration, not behavior change, on four items. All four have zero production consumers or preserve their caller's prior rule, so each is pinned as a test or corrected in prose rather than reverted. - BRACKET_PHASE_TOKEN_SOURCE: the (?=-|$) terminator is what keeps the bracket read path in step with the other surfaces, and it costs the display shapes (`05.03: Title`, `12A: X`, `05.03]` no longer tokenize). Pinned so widening the terminator class is a deliberate act rather than a lookahead deletion. - canonicalPlanStem: uppercase plan suffixes still strip, lowercase and dotted sub-plans now fall through. Dead export; pinned as a decision on record. - getMilestonePhaseFilter: `12A-01-foo` now yields `12A-01`, matching what `12-01-foo` has always yielded. The letter suffix was the only reason a sub-phase directory folded into its parent phase's milestone window; the two shapes now agree. Not named in the review — found auditing the same commit. - matchPhaseDirs docblock claimed every caller refuses on multi-match. Four do; five take matches[0]. Replaced the claim with the actual two-tier policy and the honest caveat that the bare fallback makes multi-match newly reachable for queries that previously found nothing. Co-Authored-By: Claude <noreply@anthropic.com> --------- Co-authored-by: Claude Fable 5 <noreply@anthropic.com> Co-authored-by: Tom Boucher <trekkie@nomorestars.com>
2026-08-13 05:45:04 +05:00
parent c516c39b33
commit 77374cfc32
21 changed files with 1556 additions and 103 deletions
--- a/src/init.cts
+++ b/src/init.cts
@@ -88,7 +88,7 @@ const {
  extractCurrentMilestone,
 } = roadmapParser;
 const { pathExistsInternal, generateSlugInternal, toPosixPath } = coreUtils;
-const { escapeRegex, normalizePhaseName, phaseTokenMatches, stripProjectCodePrefix, PHASE_NUMBER_TOKEN_SOURCE, isForeignPrefixedPhaseQuery, isSentinelPhaseId } = phaseId;
+const { escapeRegex, normalizePhaseName, matchPhaseDirs, stripProjectCodePrefix, PHASE_NUMBER_TOKEN_SOURCE, isForeignPrefixedPhaseQuery, isSentinelPhaseId } = phaseId;
 const { pruneOrphanedWorktrees } = worktreeSafety;

 const {
@@ -2244,7 +2244,11 @@ function cmdInitManager(cwd: string, raw: boolean): void {
    );

    try {
-      const dirMatch = _phaseDirEntries.find((d) => phaseTokenMatches(d, normalized));
+      // #3185 (ADR-3180 Decision 2) moved this lookup off the
+      // milestone-scoped set and onto the physical one; that scope choice is
+      // kept. Only the matcher is this PR's: matchPhaseDirs resolves
+      // digit-leading directory names the token predicate cannot (#2528).
+      const dirMatch = matchPhaseDirs(_phaseDirEntries, normalized).matches[0];

      if (dirMatch) {
        const fullDir = path.join(phasesDir, dirMatch);
--- a/src/milestone.cts
+++ b/src/milestone.cts
@@ -26,7 +26,7 @@ import ioMod = require('./io.cjs');
 const { output, error } = ioMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 import phaseIdMod = require('./phase-id.cjs');
-const { escapeRegex, normalizePhaseName, phaseTokenMatches, PHASE_NUMBER_TOKEN_SOURCE, isSentinelPhaseId } = phaseIdMod;
+const { escapeRegex, normalizePhaseName, matchPhaseDirs, PHASE_NUMBER_TOKEN_SOURCE, isSentinelPhaseId } = phaseIdMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 import roadmapParserMod = require('./roadmap-parser.cjs');
 const {
@@ -660,10 +660,10 @@ function cmdMilestoneComplete(cwd: string, version: string, options: MilestoneCo
        if (isSentinelPhaseId(phaseNum)) continue;
        const normalized = normalizePhaseName(phaseNum);
        // A phase has disk_status: 'no_directory' when no phase directory
-        // with a matching token exists on disk. Use the same phaseTokenMatches
-        // helper that roadmap.analyze uses to avoid false positives on decimal
-        // (2.1) and letter-suffix (12A) phase IDs.
-        const hasDirectory = phaseDirEntries.some((d) => phaseTokenMatches(d, normalized));
+        // with a matching token exists on disk. Use the same matchPhaseDirs
+        // owner that roadmap.analyze uses to avoid false positives on decimal
+        // (2.1) and letter-suffix (12A) phase IDs. (#2528)
+        const hasDirectory = matchPhaseDirs(phaseDirEntries, normalized).matches.length > 0;
        if (!hasDirectory) {
          noDirectoryPhases.push(phaseNum);
        }
--- a/src/phase-id.cts
+++ b/src/phase-id.cts
@@ -53,6 +53,25 @@ const OPTIONAL_PHASE_TAG_SOURCE = '(?:\\s*\\([^)\\n]{0,200}\\))?';
 // introduced outside this module without a `// phase-id-owner:` justification.
 const PHASE_NUMBER_TOKEN_SOURCE = '\\d+[A-Z]?(?:\\.\\d+)*';

+// #2528 review: the CASE-FLEXIBLE renderings of the two sources above, for call
+// sites that scan directory names (where a project code or a variant suffix may
+// legitimately be lowercase) and therefore cannot use a case-sensitive class.
+//
+// They live HERE, beside the sources they widen, because the alternative in use
+// was `SOURCE.replaceAll('A-Z', 'A-Za-z')` at the consuming site — a derivation
+// that depends on the owner rendering that exact literal. It passes
+// lint-phase-id-drift.cjs (no literal copy of the grammar), but the day this
+// module expresses the same class any other way (`[[:upper:]]`, a named
+// fragment, an escaped range) the replaceAll silently no-ops and the consumer
+// quietly narrows to uppercase-only — the failure is a NON-match, so nothing
+// throws and no test that only feeds uppercase input notices. Deriving it once,
+// where the source is defined, makes that impossible: a rename here is a
+// compile-visible change, not a silent behavior change three modules away.
+const CASE_FLEXIBLE_PROJECT_CODE_PREFIX_SOURCE =
+  OPTIONAL_PROJECT_CODE_PREFIX_SOURCE.replaceAll('A-Z', 'A-Za-z');
+const CASE_FLEXIBLE_PHASE_NUMBER_TOKEN_SOURCE =
+  PHASE_NUMBER_TOKEN_SOURCE.replaceAll('A-Z', 'A-Za-z');
+
 // #2232: the canonical CONTINUATION-segment grammar — a dash-separated segment
 // that extends a phase token (a zero-padded sub-phase or plan number, e.g. the
 // "01" in "02-01-setup"). getPhaseDirFromPhaseId writes these zero-padded to
@@ -64,7 +83,8 @@ const PHASE_NUMBER_TOKEN_SOURCE = '\\d+[A-Z]?(?:\\.\\d+)*';
 // trailing grammar (letter suffixes, dotted sub-phases, segment boundaries).
 // POLICY (locked by boundary tests): sub-phase/plan numbers ≥100 are out of the
 // dir-token grammar — the LEADING phase number stays unbounded (`\d+`), only
-// continuation segments are width-capped. Shared from here so the five #2043
+// continuation segments begin with a two-digit run; consuming sites retain
+// their established suffix and boundary grammar. Shared from here so the five #2043
 // call sites cannot drift independently (see scripts/lint-phase-id-drift.cjs).
 const PHASE_CONTINUATION_SEGMENT_SOURCE = '\\d{2}(?!\\d)';
 const PHASE_CONTINUATION_SEGMENT_PREFIX_RE = new RegExp(`^${PHASE_CONTINUATION_SEGMENT_SOURCE}`);
@@ -132,7 +152,8 @@ const BRACKET_PHASE_TOKEN_SOURCE =
  `\\d+[A-Z]?` +
  `(?:-${BRACKET_CANONICAL_NUMERIC_SOURCE}(?!\\d))?` +
  `(?:\\.${BRACKET_CANONICAL_NUMERIC_SOURCE}(?!\\d))?` +
-  `(?:-${PHASE_CONTINUATION_SEGMENT_SOURCE})?`;
+  `(?:-${PHASE_CONTINUATION_SEGMENT_SOURCE})?` +
+  `(?=-|$)`;

 // A phase HEADING intro under bracket is either a `[...]` bracket (optionally
 // followed by a `Phase ` label) or a bare `Phase ` label; a bare number is NOT
@@ -540,7 +561,10 @@ function extractPhaseToken(dirName: string, convention?: string): string {
      } else {
        break;
      }
-    } else if (isPhaseContinuationSegment(seg) || (firstLetterPrefixed && /^\d/.test(seg))) {
+    } else if (
+      (firstLetterPrefixed && /^\d/.test(seg)) ||
+      (!firstLetterPrefixed && isPhaseContinuationSegment(seg))
+    ) {
      tokenSegments.push(seg);
    } else {
      break;
@@ -551,6 +575,38 @@ function extractPhaseToken(dirName: string, convention?: string): string {
    return dirName;
  }

+  // #2528 (re-review): the tokenizer deliberately does NOT try to tell a 2-digit
+  // slug word ("24" of "24/7 Autonomy") from a genuine zero-padded continuation
+  // ("24" of sub-phase 10.24) — by width alone they are the same string, the gap
+  // between #2043's 1-digit and #2232's ≥3-digit guards, and no LOCAL signal
+  // separates them. An earlier revision of this fix rewound the token when the
+  // segment that stopped the scan was a 1-digit word, which reads
+  // "10-24-7-autonomy" correctly but silently re-tokenizes the equally real
+  // "10-24-7-zip" (sub-phase 10.24 named "7-Zip …") from "10-24" to "10" — it
+  // trades the reported ambiguity for the symmetric one a level down, on a
+  // CRITICAL 15-caller chokepoint whose output feeds query-less derivations
+  // (STATE.md phase counts, W007, the #2562 key surface).
+  //
+  // So the token stays the LITERAL reading of the name, and disambiguation lives
+  // ONE layer up, in matchPhaseDirs, where a QUERY exists to disambiguate
+  // against: a bare-integer lookup falls back to the directory's leading digit
+  // run and resolves "10-24-7-autonomy" for "10" without touching what the
+  // directory's own token is. That is the same bounded mechanism the
+  // "05-80-20-cleanup" shape already uses — one rule for the whole
+  // digit-leading-slug family instead of two overlapping ones.
+  //
+  // A generated slug is lowercase. If the owner admitted a two-digit prefix
+  // from a digit+letter slug segment ("10x", "25abc"), remove only that final
+  // segment. Uppercase suffixes remain available to the established plan-ID
+  // grammar, and dotted continuations remain intact.
+  if (
+    !firstLetterPrefixed &&
+    tokenSegments.length > 1 &&
+    /^\d{2}[a-z][a-z0-9]*$/.test(tokenSegments[tokenSegments.length - 1])
+  ) {
+    tokenSegments.pop();
+  }
+
  return prefix + tokenSegments.join('-');
 }

@@ -568,6 +624,122 @@ function phaseTokenMatches(dirName: string, normalized: string): boolean {
  return false;
 }

+/**
+ * #2528: the LEADING DIGIT RUN of a directory name — the fragment the
+ * bare-integer fallback selects on, and the one `phaseNumberForMatch` then
+ * displays. Named (per this module's convention of naming grammar fragments
+ * rather than inlining them) because the two sites must not drift: selecting on
+ * one run and displaying another would resolve a directory and then label it
+ * with a number that never matched.
+ *
+ * `LEADING_DIGIT_RUN_RE` anchors a trailing `-`-or-end so the run is a whole
+ * segment; `_PREFIX` is the same run without that boundary, for reading the run
+ * back off a name already known to match.
+ */
+const LEADING_DIGIT_RUN_SOURCE = '\\d+';
+const LEADING_DIGIT_RUN_RE = new RegExp(`^(${LEADING_DIGIT_RUN_SOURCE})(?:-|$)`);
+const LEADING_DIGIT_RUN_PREFIX_RE = new RegExp(`^${LEADING_DIGIT_RUN_SOURCE}`);
+const BARE_INTEGER_RE = new RegExp(`^${LEADING_DIGIT_RUN_SOURCE}$`);
+
+/** Strip leading zeros for numeric-equality compare, keeping a lone "0". */
+const unpad = (digits: string): string => digits.replace(/^0+(?=\d)/, '');
+
+/**
+ * #2528: the CANONICAL phase-directory match selection — the one rule every
+ * directory-resolution path (the shared locator plus the `find-phase` and
+ * `phase-plan-index` command scans) applies to a candidate dir list. Extracted
+ * here because the surrounding scan/ambiguity/shaping code exists per site and
+ * had already diverged; the selection itself must not.
+ *
+ * Two passes:
+ *   1. PRIMARY — exact token match (`phaseTokenMatches`), unchanged behavior.
+ *   2. BARE-INTEGER FALLBACK — only when the primary pass matched NOTHING and
+ *      the query is a bare integer, re-filter by each directory's own LEADING
+ *      digit run (zero-padded compare). This catches digit-leading slug shapes
+ *      the tokenizer cannot disambiguate from genuine sub-phase segments
+ *      (e.g. "05-80-20-cleanup", phase 5 named "80/20 Cleanup", whose token
+ *      "05-80-20" is byte-identical in shape to a real deep-decomposition dir).
+ *      The fallback can only turn a silent not-found into a resolution or into
+ *      a surfaced ambiguity (callers keep their #2237 multi-match guards) —
+ *      never override a primary match.
+ *
+ * SCOPE, precisely (#2528 re-review). Non-bare QUERIES ("46-6", "12A",
+ * "PROJ-42") never enter the fallback, so nothing changes about how a
+ * deep-decomposition or letter-suffix lookup is asked. What DOES change is the
+ * DIRECTORY side: a bare query now reaches directories the tokenizer classified
+ * as multi-segment, and a genuine sub-phase directory has exactly that shape.
+ * So `5` against a lone `05-01-auth` resolves (phase_number "05", phase_name
+ * "01-auth") where it previously found nothing.
+ *
+ * That widening is DELIBERATE and it is irreducible from directory names alone.
+ * `05-01-auth` (sub-phase 5.1) and `30-12-factor-refactor` (phase 30 named
+ * "12-Factor Refactor") are the same string shape — `NN-NN-<slug>` — and the
+ * discriminator that would separate them, "is the second segment a valid decimal
+ * sub-phase", accepts both (`5.1` and `30.12` are equally well-formed). Any rule
+ * strong enough to exclude `05-01-auth` also excludes `30-12-factor-refactor`,
+ * which is the defect #2528 exists to fix. The tie is therefore broken in favour
+ * of resolving, and the consequence is bounded on the side that matters: when
+ * BOTH readings have a directory (`05-01-auth` + `05-02-api`) the result is two
+ * matches. `tests/phase-resolution-parity.test.cjs` pins both directions: the
+ * lone-directory resolution and the two-directory refusal.
+ *
+ * WHAT IS SHARED IS SELECTION, NOT AMBIGUITY POLICY. This function is the one
+ * owner of "which directories does this query name". What a caller does with
+ * two of them stays the caller's own decision, and the callers split in two
+ * tiers on purpose:
+ *
+ *   REFUSE on `matches.length > 1` — `searchPhaseInDir`, `cmdFindPhase`,
+ *   `cmdPhasePlanIndex`, `cmdPhaseRemove`. These either act destructively or
+ *   answer "which phase is this", so guessing is worse than reporting the
+ *   candidates (#2237).
+ *
+ *   TAKE `matches[0]` — `cmdPhasesList`, `cmdInitManager`, `cmdRoadmapAnalyze`,
+ *   `cmdVerifySchemaDrift`, `detectVerifyFailed`. Each read a directory to
+ *   DECORATE a row they are already emitting; each used `.find()` before this
+ *   PR, so first-match is their prior behavior preserved verbatim, and each is
+ *   order-stable because the directory list is sorted and this function filters
+ *   without reordering.
+ *
+ * The honest caveat on that second tier: the bare-number fallback makes
+ * multi-match newly REACHABLE for inputs that previously found nothing, so those
+ * five can now silently pick one of several candidates where they used to report
+ * not-found. That is a widening of an existing first-match rule, not a new rule
+ * — but it is a widening, and promoting any of them to refusal is a UX decision
+ * about their own output, not a change to selection, so it does not belong here.
+ *
+ * `usedBareFallback` tells callers to derive the displayed phase number from
+ * the directory's leading digit run instead of `extractPhaseToken` (whose
+ * token for these dirs is the mis-absorbed multi-segment form).
+ */
+function matchPhaseDirs(dirs: string[], normalized: string): { matches: string[]; usedBareFallback: boolean } {
+  const primary = dirs.filter(d => phaseTokenMatches(d, normalized));
+  if (primary.length > 0) return { matches: primary, usedBareFallback: false };
+
+  const bare = String(normalized);
+  if (!BARE_INTEGER_RE.test(bare)) return { matches: primary, usedBareFallback: false };
+  const want = unpad(bare);
+
+  const fallback = dirs.filter(d => {
+    const m = stripProjectCodePrefix(d).match(LEADING_DIGIT_RUN_RE);
+    return m !== null && unpad(m[1]) === want;
+  });
+  return { matches: fallback, usedBareFallback: fallback.length > 0 };
+}
+
+/**
+ * #2528: the display phase number for a directory selected by matchPhaseDirs.
+ * Primary matches keep the extracted token; bare-fallback matches use the
+ * directory's leading digit run (the whole point of the fallback is that the
+ * extracted token is wrong for these dirs).
+ */
+function phaseNumberForMatch(dirName: string, usedBareFallback: boolean): string {
+  if (!usedBareFallback) return extractPhaseToken(dirName);
+  const stripped = stripProjectCodePrefix(dirName);
+  const prefix = dirName.slice(0, dirName.length - stripped.length);
+  const m = stripped.match(LEADING_DIGIT_RUN_PREFIX_RE);
+  return m ? prefix + m[0] : extractPhaseToken(dirName);
+}
+
 // ─── Canonical phase KEY surface (#2562) ─────────────────────────────────────
 //
 // A phase "key" is the padding-, case- and project-code-insensitive identity of
@@ -756,6 +928,8 @@ export = {
  OPTIONAL_PROJECT_CODE_PREFIX_SOURCE,
  OPTIONAL_PHASE_TAG_SOURCE,
  PHASE_NUMBER_TOKEN_SOURCE,
+  CASE_FLEXIBLE_PROJECT_CODE_PREFIX_SOURCE,
+  CASE_FLEXIBLE_PHASE_NUMBER_TOKEN_SOURCE,
  PHASE_CONTINUATION_SEGMENT_SOURCE,
  isPhaseContinuationSegment,
  BRACKET_PHASE_TOKEN_SOURCE,
@@ -774,6 +948,8 @@ export = {
  comparePhaseNum,
  extractPhaseToken,
  phaseTokenMatches,
+  matchPhaseDirs,
+  phaseNumberForMatch,
  phaseKeyFromToken,
  phaseKeyFromDir,
  phaseKeyFromProse,
--- a/src/phase-locator.cts
+++ b/src/phase-locator.cts
@@ -11,7 +11,7 @@
 *
 * Dependencies (leaf modules only — no loadConfig):
 *   - node:fs / node:path (stdlib)
- *   - ./phase-id.cjs       (normalizePhaseName, phaseTokenMatches, extractPhaseToken)
+ *   - ./phase-id.cjs       (normalizePhaseName, matchPhaseDirs, phaseNumberForMatch)
 *   - ./core-utils.cjs     (readSubdirectories, getPhaseFileStats, extractCanonicalPlanId, toPosixPath)
 *   - ./planning-workspace.cjs (planningDir)
 */
@@ -20,7 +20,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 import phaseIdModule = require('./phase-id.cjs');
-const { normalizePhaseName, phaseTokenMatches, extractPhaseToken, isSentinelPhaseId, comparePhaseNum } = phaseIdModule;
+const { normalizePhaseName, matchPhaseDirs, phaseNumberForMatch, isSentinelPhaseId, comparePhaseNum } = phaseIdModule;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 import coreUtilsModule = require('./core-utils.cjs');
 const { readSubdirectories, getPhaseFileStats, extractCanonicalPlanId, toPosixPath, findUnsummarizedPlans } = coreUtilsModule;
@@ -147,7 +147,10 @@ function listArchiveVersionDirs(cwd: string): ArchiveVersionDir[] {
 function searchPhaseInDir(baseDir: string, relBase: string, normalized: string): PhaseSearchResult | null {
  try {
    const dirs = readSubdirectories(baseDir, true);
-    const matches = dirs.filter(d => phaseTokenMatches(d, normalized));
+    // #2528: canonical two-pass selection (exact token match, then the
+    // bare-integer leading-digit-run fallback) shared with the find-phase and
+    // phase-plan-index scans — see phase-id.cts::matchPhaseDirs.
+    const { matches, usedBareFallback } = matchPhaseDirs(dirs, normalized);
    if (matches.length === 0) return null;

    // #2237: fail loud when multiple directories match the same bare phase
@@ -176,7 +179,7 @@ function searchPhaseInDir(baseDir: string, relBase: string, normalized: string):

    const match = matches[0];

-    const phaseToken = extractPhaseToken(match);
+    const phaseToken = phaseNumberForMatch(match, usedBareFallback);
    const phaseNumber = phaseToken || normalized;
    const afterToken = match.slice(phaseToken ? phaseToken.length : 0).replace(/^-/, '');
    const phaseName = afterToken || null;
--- a/src/phase.cts
+++ b/src/phase.cts
@@ -26,7 +26,15 @@ import configLoaderMod = require('./config-loader.cjs');
 const { loadConfig } = configLoaderMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports -- core-utils.cjs is an export= CommonJS module
 import coreUtilsMod = require('./core-utils.cjs');
-const { toPosixPath, generateSlugInternal, readSubdirectories, findUnsummarizedPlans } = coreUtilsMod;
+// #2528: `extractCanonicalPlanId` used to exist here as a byte-identical second
+// copy, and this PR had to patch BOTH with the same rewind rule — the exact
+// generative-fix divergence CLAUDE.md warns about. Collapsed onto core-utils'
+// copy, which was already the leaf owner, so there is no second surface left to
+// drift and no parity test needed to police one.
+const {
+  toPosixPath, generateSlugInternal, readSubdirectories, extractCanonicalPlanId,
+  findUnsummarizedPlans,
+} = coreUtilsMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports -- phase-id.cjs is an export= CommonJS module
 import phaseIdMod = require('./phase-id.cjs');
 const {
@@ -34,7 +42,7 @@ const {
  normalizePhaseName,
  phaseMarkdownRegexSource,
  comparePhaseNum,
-  phaseTokenMatches,
+  matchPhaseDirs,
  isSentinelPhaseId,
  OPTIONAL_PROJECT_CODE_PREFIX_SOURCE,
  OPTIONAL_PHASE_TAG_SOURCE,
@@ -164,30 +172,6 @@ function describeNonCanonicalPlans(dirFiles: string[], matchedFiles: string[]):
  );
 }

-function extractCanonicalPlanId(filename: string): string {
-  const base = filename
-    .replace(/-PLAN\.md$/i, '')
-    .replace(/-SUMMARY\.md$/i, '')
-    .replace(/\.md$/i, '');
-  const parts = base.split('-').filter(Boolean);
-  // #2043: a phase/plan token component is either a zero-padded number (≥2 digits)
-  // or a single-digit-plus-letter id ("3A"); a *bare* single digit is a slug word,
-  // so "46-6-rs-…" is not paired into a "46-6" id while "3A-01" stays intact.
-  const tokenRe = /^(?:\d{2,}[A-Z]?|\d[A-Z])(?:\.\d+)*$/i;
-  // #2232: the PAIRED plan component is a zero-padded continuation segment
-  // (exactly 2 digits), so a ≥3-digit slug word (a year) is not paired into a
-  // bogus "14-2026" id. The leading phase component keeps tokenRe's unbounded
-  // \d{2,} — phase numbers ≥100 are legitimate; only continuations are capped.
-  const planTokenRe = new RegExp(
-    `^(?:${phaseIdMod.PHASE_CONTINUATION_SEGMENT_SOURCE}[A-Z]?|\\d[A-Z])(?:\\.\\d+)*$`,
-    'i',
-  );
-  const phaseIdx = parts.findIndex((p) => tokenRe.test(p));
-  if (phaseIdx >= 0 && phaseIdx + 1 < parts.length && planTokenRe.test(parts[phaseIdx + 1])) {
-    return `${parts[phaseIdx]}-${parts[phaseIdx + 1]}`;
-  }
-  return base;
-}

 interface PhaseListOptions {
  type?: string;
@@ -241,7 +225,11 @@ function cmdPhasesList(cwd: string, options: PhaseListOptions, raw: boolean): vo
      // LOOKUP (b): search the physical set, plus archived when asked.
      const lookupPool = [...readSubdirectories(phasesDir, true), ...archivedLabels];
      const normalized = normalizePhaseName(phase);
-      const match = lookupPool.find((d) => phaseTokenMatches(d, normalized));
+      // The pool is #3185's (physical set + archived); the matcher is this
+      // PR's. `dirs` is deliberately not read here: on this base it is not
+      // assigned until the branch below picks a match.
+      const { matches } = matchPhaseDirs(lookupPool, normalized);
+      const match = matches[0];
      if (!match) {
        output({ files: [], count: 0, phase_dir: null, error: 'Phase not found' }, raw, '');
        return;
@@ -328,7 +316,7 @@ function cmdPhaseNextDecimal(cwd: string, basePhase: string, raw: boolean): void
    if (fs.existsSync(phasesDir)) {
      const entries = fs.readdirSync(phasesDir, { withFileTypes: true });
      const dirs = entries.filter((e) => e.isDirectory()).map((e) => e.name);
-      baseExists = dirs.some((d) => phaseTokenMatches(d, normalized));
+      baseExists = matchPhaseDirs(dirs, normalized).matches.length > 0;

      const dirPattern = new RegExp(`^${OPTIONAL_PROJECT_CODE_PREFIX_SOURCE}${escapeRegex(normalized)}\\.(\\d+)`);
      for (const dir of dirs) {
@@ -502,7 +490,10 @@ function cmdFindPhase(cwd: string, phase: string, raw: boolean): void {
      // #2237: fail loud when multiple directories match the same bare phase
      // number — prevents cross-project file writes when unrelated projects
      // share a .planning/phases/ tree.
-      const matches = dirs.filter((d) => phaseTokenMatches(d, normalized));
+      // #2528: selection delegates to the canonical two-pass matcher (exact
+      // token match, then the bare-integer leading-digit-run fallback) shared
+      // with the locator and the phase-plan-index scan.
+      const { matches } = matchPhaseDirs(dirs, normalized);
      if (matches.length === 0) continue;
      if (matches.length > 1) {
        output({
@@ -692,21 +683,41 @@ function cmdPhasePlanIndex(cwd: string, phase: string, raw: boolean): void {

  let phaseDir: string | null = null;
  let phaseDirName: string | null = null;
+  let ambiguousMatches: string[] | null = null;
  try {
    const entries = fs.readdirSync(phasesDir, { withFileTypes: true });
    const dirs = entries
      .filter((e) => e.isDirectory())
      .map((e) => e.name)
      .sort((a, b) => comparePhaseNum(a, b));
-    const match = dirs.find((d) => phaseTokenMatches(d, normalized));
-    if (match) {
-      phaseDir = path.join(phasesDir, match);
-      phaseDirName = match;
+    // #2528: selection delegates to the canonical two-pass matcher shared with
+    // the locator and the find-phase scan (this site previously first-matched
+    // with `.find()` and had no multi-match guard — the #2237 fail-loud rule
+    // now applies here too, so the three resolution paths cannot disagree).
+    const { matches } = matchPhaseDirs(dirs, normalized);
+    if (matches.length > 1) {
+      ambiguousMatches = matches;
+    } else if (matches.length === 1) {
+      phaseDir = path.join(phasesDir, matches[0]);
+      phaseDirName = matches[0];
    }
  } catch {
    // phases dir doesn't exist
  }

+  if (ambiguousMatches) {
+    output(
+      {
+        phase: normalized,
+        error: `Phase ${normalized} is ambiguous: ${ambiguousMatches.length} directories match (${ambiguousMatches.map((m) => `"${m}"`).join(', ')}).`,
+        ambiguous_matches: ambiguousMatches,
+        plans: [], waves: {}, incomplete: [], has_checkpoints: false,
+      },
+      raw,
+    );
+    return;
+  }
+
  if (!phaseDir) {
    output(
      { phase: normalized, error: 'Phase not found', plans: [], waves: {}, incomplete: [], runnable: [], has_checkpoints: false },
@@ -1750,7 +1761,32 @@ function cmdPhaseRemove(
  const force = options.force || false;

  const subdirs = readSubdirectories(phasesDir, true);
-  const targetDir = subdirs.find((d) => phaseTokenMatches(d, normalized)) || null;
+  // #2237/#2528: every other resolution path refuses to choose between multiple
+  // directories claiming one phase number. This one is the DESTRUCTIVE path, so
+  // taking `matches[0]` silently is strictly worse than anywhere else: it turns
+  // "resolve nothing" into "delete one of two candidates, unrecoverably, and
+  // renumber every phase after it". Refuse before any file is touched.
+  const { matches: phaseDirMatches } = matchPhaseDirs(subdirs, normalized);
+  if (phaseDirMatches.length > 1) {
+    output(
+      {
+        removed: null,
+        error:
+          `Phase ${normalized} is ambiguous: ${phaseDirMatches.length} directories match `
+          + `(${phaseDirMatches.map((m) => `"${m}"`).join(', ')}). Refusing to remove any of them. `
+          + 'Set a distinct project_code in .planning/config.json, or pass the full directory name.',
+        ambiguous_matches: phaseDirMatches,
+        directory_deleted: null,
+        renamed_directories: [],
+        renamed_files: [],
+        roadmap_updated: false,
+        state_updated: false,
+      },
+      raw,
+    );
+    return;
+  }
+  const targetDir = phaseDirMatches[0] || null;

  if (targetDir && !force) {
    // #3183: canonical summary set (root+nested) from the single owner —
@@ -1838,9 +1874,17 @@ function cmdPhaseRemove(
        if (targetDir && modified === stateContent) {
          // subdirs was read before the deletion; excluding the removed target
          // gives the remaining count. Renumbering changes names but not count.
-          const remainingPhases = subdirs.filter(
-            (d) => phaseTokenMatches(d, normalized) === false,
-          ).length;
+          //
+          // #2528: exclude the directory that was ACTUALLY deleted, by identity,
+          // rather than re-deriving "which dir was the target" from the query.
+          // The two are not the same predicate here: `targetDir` comes from
+          // `matchPhaseDirs`, whose bare-integer fallback resolves digit-leading
+          // dirs (`05-80-20-cleanup` for query `5`) that `phaseTokenMatches`
+          // reports as non-matching — so a token re-derivation would count the
+          // just-deleted directory as still present and write a `Total Phases`
+          // one too high. Identity is also what the comment above already
+          // claims this filter does, and the block is gated on targetDir.
+          const remainingPhases = subdirs.filter((d) => d !== targetDir).length;
          if (totalRaw) {
            modified =
              stateReplaceField(modified, 'Total Phases', String(remainingPhases)) || modified;
--- a/src/roadmap-parser.cts
+++ b/src/roadmap-parser.cts
@@ -1379,7 +1379,7 @@ function getMilestonePhaseFilter(cwd: string, versionOverride?: string | null, p
  // Built via new RegExp (no /i — the [A-Za-z] letter class does real case handling).
  const numericRe = roadmapUsesHyphenedIds
    ? new RegExp(
-        `^0*(\\d+(?:-${phaseIdModule.PHASE_CONTINUATION_SEGMENT_SOURCE})*[A-Za-z]?(?:\\.\\d+)*)`,
+        `^0*(\\d+[A-Za-z]?(?:-${phaseIdModule.PHASE_CONTINUATION_SEGMENT_SOURCE}[A-Z]?)*(?:\\.\\d+)*)(?=-|$)`,
      )
    // phase-id-owner: the [A-Za-z] letter class does real case handling here — this regex carries NO /i flag; kept literal, not source-byte-equal to the canonical PHASE_NUMBER_TOKEN_SOURCE.
    : /^0*(\d+[A-Za-z]?(?:\.\d+)*)/;
--- a/src/roadmap.cts
+++ b/src/roadmap.cts
@@ -14,7 +14,7 @@ import ioMod = require('./io.cjs');
 const { output, error } = ioMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 import phaseIdMod = require('./phase-id.cjs');
-const { escapeRegex, normalizePhaseName, phaseMarkdownRegexSource, phaseTokenMatches, stripProjectCodePrefix, OPTIONAL_PHASE_TAG_SOURCE, roadmapPhaseLookupSources, isSentinelPhaseId } = phaseIdMod;
+const { escapeRegex, normalizePhaseName, phaseMarkdownRegexSource, matchPhaseDirs, stripProjectCodePrefix, OPTIONAL_PHASE_TAG_SOURCE, roadmapPhaseLookupSources, isSentinelPhaseId } = phaseIdMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 import phaseLocatorMod = require('./phase-locator.cjs');
 const { findPhaseInternal, listMilestonePhaseDirs } = phaseLocatorMod;
@@ -400,13 +400,13 @@ function cmdRoadmapAnalyze(cwd: string, raw: boolean): void {
    let hasContext = false;
    let hasResearch = false;

-    // DEAD catch removed (#2245 audit): _phaseDirNames.find(...) is a pure
+    // DEAD catch removed (#2245 audit): matchPhaseDirs(...) is a pure
    // array lookup on an already-resolved string array, and
    // countPhasePlansAndSummaries is itself fully defensive (its own
    // readdirSync is self-guarded, and it delegates to scanPhasePlans, which
    // never throws) — nothing in this block can throw, so the try/catch could
    // never be triggered.
-    const dirMatch = _phaseDirNames.find(d => phaseTokenMatches(d, normalized));
+    const dirMatch = matchPhaseDirs(_phaseDirNames, normalized).matches[0];

    if (dirMatch) {
      const counts = countPhasePlansAndSummaries(path.join(phasesDir, dirMatch));
--- a/src/smart-entry.cts
+++ b/src/smart-entry.cts
@@ -50,7 +50,7 @@ import stateDocument = require('./state-document.cjs');
 const { stateFieldValue } = stateDocument;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 import phaseId = require('./phase-id.cjs');
-const { comparePhaseNum, extractPhaseToken, normalizePhaseName, phaseTokenMatches } = phaseId;
+const { comparePhaseNum, extractPhaseToken, matchPhaseDirs, normalizePhaseName, stripProjectCodePrefix } = phaseId;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 import stateMod = require('./state.cjs');
 const { readStateHeadFreshness } = stateMod;
@@ -173,7 +173,15 @@ function parseIntOrNull(s: string | null): number | null {

 function phaseTokenFromDirName(name: string): string | null {
  const token = extractPhaseToken(name);
-  return /^\d+(?:[A-Z])?(?:\.\d+)*(?:-|$)/i.test(token) ? token : null;
+  // #2528: the shape probe runs on the PROJECT-CODE-STRIPPED token. A prefixed
+  // directory tokenizes to `MEM-05-80-20`, which does not start with a digit,
+  // so the unstripped probe rejected it and the entry was dropped before any
+  // resolution ran — every phase in a project-coded plan was invisible here.
+  // The full token is still what is returned: `comparePhaseNum` strips the
+  // prefix itself, so the sort is unaffected, and `matchPhaseDirs` needs the
+  // real directory name.
+  const probe = stripProjectCodePrefix(token);
+  return /^\d+(?:[A-Z])?(?:\.\d+)*(?:-|$)/i.test(probe) ? token : null;
 }

 /**
@@ -251,7 +259,16 @@ function detectVerifyFailed(cwd: string, currentPhaseRaw: string | null): boolea
  let targetDir: string | undefined;
  if (phaseToken) {
    const normalized = normalizePhaseName(phaseToken);
-    targetDir = entries.find((name) => phaseTokenMatches(name, normalized));
+    // #2528: the fourth directory-resolution site, and the one where a miss is
+    // silent — a phase whose directory cannot be found reports "not failed",
+    // which reads identically to a healthy phase. It must therefore apply the
+    // same canonical selection as the locator and the two command scans, or a
+    // dir like `05-80-20-cleanup` (phase 5 named "80/20 Cleanup") never
+    // surfaces its own failed verification. `entries` is already sorted, and
+    // `matchPhaseDirs` filters without reordering, so taking the first match
+    // preserves the previous `.find()` selection exactly.
+    const { matches } = matchPhaseDirs(entries, normalized);
+    targetDir = matches[0];
    if (!targetDir) return false;
  } else {
    // No current phase in state — fall back to the highest-numbered phase dir.
--- a/src/validate.cts
+++ b/src/validate.cts
@@ -35,7 +35,12 @@
 import phaseIdMod = require('./phase-id.cjs');
 const {
  OPTIONAL_PROJECT_CODE_PREFIX_SOURCE,
-  PHASE_NUMBER_TOKEN_SOURCE,
+  // #2528 review: taken from the owner rather than derived here by
+  // `replaceAll('A-Z', 'A-Za-z')` — that derivation silently no-ops (and narrows
+  // this module to uppercase-only) the day phase-id.cts renders the class any
+  // other way. See the constants' doc comment in phase-id.cts.
+  CASE_FLEXIBLE_PROJECT_CODE_PREFIX_SOURCE,
+  CASE_FLEXIBLE_PHASE_NUMBER_TOKEN_SOURCE,
  PHASE_CONTINUATION_SEGMENT_SOURCE,
 } = phaseIdMod;

@@ -46,21 +51,28 @@ export const phaseDirNameRe = new RegExp(
  `^${OPTIONAL_PROJECT_CODE_PREFIX_SOURCE}\\d{2,}(?:-\\d+)*(?:\\.\\d+)*-[\\w-]+$`,
  'i',
 );
-// Extracts the full phase token from a directory name, including milestone-prefixed
-// multi-segment tokens like "02-01" from "02-01-setup" or "GSD-02-01-setup".
+// Extracts the full phase token from a directory name, including project-code and
+// milestone prefixes plus multi-segment tokens like "02-01" from "02-01-setup"
+// or "GSD-02-01" from "GSD-02-01-setup". The capture intentionally matches
+// extractPhaseToken() exactly; health-validation consumers strip the project code
+// only where their historical disk/roadmap comparison requires a numeric token.
 // #2043: a *continuation* sub-phase segment must be zero-padded, so a
 // single-digit slug word after a phase number (e.g. "46-6-rs-…", slug "6 Rs …") is
 // NOT absorbed — it captures "46", not "46-6". #2232: the continuation width is
 // exactly 2 (PHASE_CONTINUATION_SEGMENT_SOURCE), so a ≥3-digit slug word (a year:
 // "14-2026-photos-…") is not absorbed either — it captures "14", not "14-2026".
-// The first component stays "\d+"
+// #2528: this regex stays the LITERAL reading of the name and does NOT try to
+// re-classify an absorbed 2-digit continuation as a slug word — see the
+// extractPhaseToken doc comment for why that is a resolution-layer job
+// (matchPhaseDirs), not a tokenizer one. The two surfaces must agree, and they
+// agree on the literal reading. The first component stays "\d+"
 // (with the "[A-Z]?" suffix) so single-digit letter-suffixed phase ids ("1A") and
 // milestone-prefixed single-digit sub-phases ("M1-2" → prefix "M1-" stripped, then
 // "2") still match. The trailing boundary "(?:-|$)" (was "(?:-[a-z]|$)") lets a slug
 // that starts with a digit terminate the token.
 export const PHASE_TOKEN_FROM_DIR_RE = new RegExp(
-  `^${OPTIONAL_PROJECT_CODE_PREFIX_SOURCE}(\\d+(?:-${PHASE_CONTINUATION_SEGMENT_SOURCE})*[A-Z]?(?:\\.\\d+)*)(?:-|$)`,
-  'i',
+  `^(${CASE_FLEXIBLE_PROJECT_CODE_PREFIX_SOURCE}` +
+  `\\d+[A-Za-z]?(?:-${PHASE_CONTINUATION_SEGMENT_SOURCE}[A-Z]?)*(?:\\.\\d+)*)(?:-|$)`,
 );
 export const MILESTONE_ARCHIVE_DIR_RE = /^v\d+.*-phases$/i;

@@ -71,7 +83,10 @@ export function canonicalPlanStem(stem: string): string {
  // for a "46-6" phase/plan pair. #2232: exactly 2 digits, so a year-leading
  // slug ("14-2026-photos-…") is not mistaken for a "14-2026" pair either.
  const m = stem.match(
-    new RegExp(`^(${PHASE_NUMBER_TOKEN_SOURCE}-${PHASE_CONTINUATION_SEGMENT_SOURCE})`, 'i'),
+    new RegExp(
+      `^(${CASE_FLEXIBLE_PHASE_NUMBER_TOKEN_SOURCE}-${PHASE_CONTINUATION_SEGMENT_SOURCE})` +
+      `(?=[A-Z](?:-|$)|-|$)`,
+    ),
  );
  return m ? m[1] : stem;
 }
--- a/src/verify.cts
+++ b/src/verify.cts
@@ -46,7 +46,7 @@ import configLoaderMod = require('./config-loader.cjs');
 const { loadConfig, CONFIG_DEFAULTS } = configLoaderMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 import phaseIdMod = require('./phase-id.cjs');
-const { normalizePhaseName, phaseTokenMatches, escapeRegex, getMilestoneFromPhaseId, OPTIONAL_PHASE_TAG_SOURCE, PHASE_NUMBER_TOKEN_SOURCE, extractPhaseToken, comparePhaseNum, isSentinelPhaseId } = phaseIdMod;
+const { normalizePhaseName, matchPhaseDirs, escapeRegex, getMilestoneFromPhaseId, OPTIONAL_PHASE_TAG_SOURCE, PHASE_NUMBER_TOKEN_SOURCE, extractPhaseToken, stripProjectCodePrefix, comparePhaseNum, isSentinelPhaseId } = phaseIdMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 import phaseLocatorMod = require('./phase-locator.cjs');
 const { findPhaseInternal } = phaseLocatorMod;
@@ -1313,7 +1313,7 @@ function forEachArchivedPhaseToken(planBase: string, onPhase: (token: string) =>
      for (const e of entries) {
        if (!e.isDirectory()) continue;
        const m = e.name.match(PHASE_TOKEN_FROM_DIR_RE);
-        if (m) onPhase(m[1]);
+        if (m) onPhase(stripProjectCodePrefix(m[1]));
      }
    } catch {
      /* archive dir absent/unreadable */
@@ -1354,8 +1354,24 @@ function collectPhaseRoots(planBase: string): string[] {
  return roots;
 }

-function collectDiskPhases(planBase: string): Set<string> {
-  const diskPhases = new Set<string>();
+/**
+ * #2528: the disk-side phase inventory, keyed by extracted token but KEEPING the
+ * directory names behind each token.
+ *
+ * The token alone is what made `validate health` the ninth site of the #2528
+ * class. W006/W007 pair roadmap phases against disk by intersecting TOKEN SETS
+ * (`phaseVariants(p)` vs these keys), which is a dir→token labelling, not the
+ * query→dir selection `matchPhaseDirs` owns — so a `grep phaseTokenMatches`
+ * never surfaced it. On a digit-leading slug the label is wrong in both
+ * directions at once: `05-80-20-cleanup` labels itself `05-80-20`, so phase 5
+ * "has no directory" (W006) AND that directory "is not in the roadmap" (W007).
+ *
+ * Carrying the names lets both warnings ask the canonical matcher whether a
+ * roadmap phase actually resolves to a directory, instead of asking whether two
+ * independently-derived labels happen to be equal.
+ */
+function collectDiskPhaseEntries(planBase: string): Map<string, string[]> {
+  const entriesByToken = new Map<string, string[]>();
  const phaseRoots = collectPhaseRoots(planBase);
  const scanDir = (dir: string) => {
    try {
@@ -1363,7 +1379,11 @@ function collectDiskPhases(planBase: string): Set<string> {
      for (const e of entries) {
        if (e.isDirectory()) {
          const m = e.name.match(PHASE_TOKEN_FROM_DIR_RE);
-          if (m) diskPhases.add(m[1]);
+          if (!m) continue;
+          const token = stripProjectCodePrefix(m[1]);
+          const dirs = entriesByToken.get(token);
+          if (dirs) dirs.push(e.name);
+          else entriesByToken.set(token, [e.name]);
        }
      }
    } catch {
@@ -1373,7 +1393,31 @@ function collectDiskPhases(planBase: string): Set<string> {

  for (const root of phaseRoots) scanDir(root);

-  return diskPhases;
+  return entriesByToken;
+}
+
+function collectDiskPhases(planBase: string): Set<string> {
+  return new Set(collectDiskPhaseEntries(planBase).keys());
+}
+
+/**
+ * #2528: archived phase DIRECTORY NAMES, the name-side twin of
+ * `forEachArchivedPhaseToken`. W006 must not warn about a roadmap phase whose
+ * only directory lives in a shipped-milestone archive, and deciding that needs
+ * the same name-based resolution the active roots get.
+ */
+function collectArchivedPhaseDirNames(planBase: string): string[] {
+  const names: string[] = [];
+  for (const archiveDir of listMilestoneArchiveDirs(planBase)) {
+    try {
+      for (const e of fs.readdirSync(archiveDir, { withFileTypes: true })) {
+        if (e.isDirectory() && PHASE_TOKEN_FROM_DIR_RE.test(e.name)) names.push(e.name);
+      }
+    } catch {
+      /* archive dir absent/unreadable */
+    }
+  }
+  return names;
 }

 interface MilestoneMismatch {
@@ -1987,13 +2031,36 @@ function cmdValidateHealth(
    const roadmapContent = extractCurrentMilestone(roadmapContentRaw, cwd);

    const { roadmapPhases } = buildRoadmapPhaseVariants(roadmapContent);
-    const { roadmapPhaseVariants: fullRoadmapPhaseVariants } =
+    const { roadmapPhases: fullRoadmapPhases, roadmapPhaseVariants: fullRoadmapPhaseVariants } =
      buildRoadmapPhaseVariants(roadmapContentRaw);

    const diskPhases = collectDiskPhases(planBase);
    forEachArchivedPhaseToken(planBase, (token) => diskPhases.add(token));

-    const activeDiskPhases = collectDiskPhases(planBase);
+    const activeDiskEntries = collectDiskPhaseEntries(planBase);
+
+    // #2528: the name side of the same inventory. The token sets above answer
+    // "do two independently-derived labels agree"; these answer "does the
+    // canonical matcher resolve this roadmap phase to a real directory" — the
+    // question W006/W007 are actually asking. Both are kept: the token
+    // intersection still decides every shape it already decided correctly, and
+    // the resolution below only ever REMOVES a warning, so a phase the tokens
+    // already paired up cannot start warning because of this.
+    const activeDirNames = [...activeDiskEntries.values()].flat();
+    const allDirNames = [...activeDirNames, ...collectArchivedPhaseDirNames(planBase)];
+
+    // A directory is CLAIMED when some roadmap phase resolves to it. This is the
+    // inverse mapping W007 never had: it iterates directories, so it has no query
+    // to resolve, and a dir whose label does not appear in the roadmap looked
+    // orphaned even when the roadmap phase that owns it resolves to it exactly.
+    // Built from the FULL roadmap (shipped milestones included), matching the
+    // variant set W007 already compares against.
+    const claimedDirs = new Set<string>();
+    for (const p of fullRoadmapPhases) {
+      for (const d of matchPhaseDirs(activeDirNames, normalizePhaseName(p)).matches) {
+        claimedDirs.add(d);
+      }
+    }

    const notStartedPhases = buildNotStartedPhaseVariants(roadmapContent);

@@ -2002,7 +2069,8 @@ function cmdValidateHealth(
      // a sentinel heading shouldn't demand a directory.
      if (isSentinelPhaseId(p)) continue;
      const variants = phaseVariants(p);
-      const existsOnDisk = [...variants].some((v) => diskPhases.has(v));
+      const existsOnDisk = [...variants].some((v) => diskPhases.has(v))
+        || matchPhaseDirs(allDirNames, normalizePhaseName(p)).matches.length > 0;
      if (!existsOnDisk) {
        const isNotStarted = [...variants].some((v) => notStartedPhases.has(v));
        if (isNotStarted) continue;
@@ -2015,21 +2083,21 @@ function cmdValidateHealth(
      }
    }

-    for (const p of activeDiskPhases) {
+    for (const [p, dirsForToken] of activeDiskEntries) {
      // #3225: a sentinel dir on disk (999-interim, 0-drafts) is defined as
      // never-on-roadmap; it must not trigger W007 ("Add to roadmap or remove
      // directory" — both wrong for a sentinel). Mirrors the isSentinelPhaseId
      // guard phase.cts has at 10+ sites (#2786/#2949).
      if (isSentinelPhaseId(p)) continue;
      const variants = phaseVariants(p);
-      if (![...variants].some((v) => fullRoadmapPhaseVariants.has(v))) {
-        addIssue(
-          'warning',
-          'W007',
-          `Phase ${p} exists on disk but not in ROADMAP.md`,
-          'Add to roadmap or remove directory',
-        );
-      }
+      if ([...variants].some((v) => fullRoadmapPhaseVariants.has(v))) continue;
+      if (dirsForToken.every((d) => claimedDirs.has(d))) continue;
+      addIssue(
+        'warning',
+        'W007',
+        `Phase ${p} exists on disk but not in ROADMAP.md`,
+        'Add to roadmap or remove directory',
+      );
    }
  }

@@ -2315,7 +2383,7 @@ function cmdValidateHealth(
        while ((pm = phasePattern.exec(scopedContent)) !== null) {
          const phaseNum = pm[1];
          const normalizedPh = normalizePhaseName(phaseNum);
-          const hasDirectory = phaseDirNames2.some((d) => phaseTokenMatches(d, normalizedPh));
+          const hasDirectory = matchPhaseDirs(phaseDirNames2, normalizedPh).matches.length > 0;
          if (!hasDirectory) {
            unstarted.push(phaseNum);
          }
@@ -2549,21 +2617,19 @@ function cmdVerifySchemaDrift(
    return;
  }

-  // Resolve the phase directory with the canonical phase-token matcher
-  // (phase-id.cjs), not a naive substring test. A bare `.includes(phaseArg)`
-  // lets a non-existent phase silently match a different phase whose directory
-  // name merely contains the requested token (e.g. "1" matching "11-expansion"),
-  // making the drift gate inspect the wrong phase. This mirrors find-phase /
-  // verify phase-completeness, which both use phaseTokenMatches. (#1571)
+  // Resolve the phase directory with the canonical phase-directory matcher
+  // (phase-id.cjs::matchPhaseDirs), not a naive substring test. A bare
+  // `.includes(phaseArg)` lets a non-existent phase silently match a different
+  // phase whose directory name merely contains the requested token (e.g. "1"
+  // matching "11-expansion"), making the drift gate inspect the wrong phase.
+  // This shares the one selection rule with find-phase / verify
+  // phase-completeness rather than restating it. (#1571, #2528)
  let phaseDir: string | null = null;
  const normalizedPhase = normalizePhaseName(phaseArg);
  const entries = fs.readdirSync(phasesDir, { withFileTypes: true });
-  for (const entry of entries) {
-    if (entry.isDirectory() && phaseTokenMatches(entry.name, normalizedPhase)) {
-      phaseDir = path.join(phasesDir, entry.name);
-      break;
-    }
-  }
+  const dirNames = entries.filter((e) => e.isDirectory()).map((e) => e.name);
+  const drift = matchPhaseDirs(dirNames, normalizedPhase).matches[0];
+  if (drift) phaseDir = path.join(phasesDir, drift);

  if (!phaseDir) {
    const exact = path.join(phasesDir, phaseArg);