3 Commits

Author	SHA1	Message	Date
JusticeWay	77374cfc32	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-12 20:45:04 -04:00
BeeHiggs	bf9fe4630d	feat(#2249): bracket phase-id core grammar — parse/render/toDir round-trip pair (epic #612 PR-1) (#2258) ... * feat(#2249): bracket phase-id core grammar — parse/render/toDir + READING-B + guards PR-1 of epic #612 (ADR-612, in-tree at docs/adr/612-bracket-phase-id-convention.md). Adds the bracket-convention grammar INSIDE src/phase-id.cts — the ADR-2121 single canonical owner — as a pure, additive extension. The 17 locked exports and PHASE_NUMBER_TOKEN_SOURCE are untouched, and normalizePhaseName is byte-identical, so the PR-0 collision anchor (tests/adr-612-collision-characterization.test.cjs) stays green. New pure round-trippable model (ADR Decision 4): - PhaseId { project, milestone, phase, subphase?, plan? }. - parsePhaseId(input): accepts display `[GSD.02] 05.03-01`, dir/token `GSD.02-05.03-slug`, or bare `GSD.02-05`; rejects ambiguous non-bracket tokens (`02-04`, `05`) rather than guessing. The rejection lives ONLY in this new parser — normalizePhaseName and every legacy reader keep accepting those tokens unchanged (conservative default; no existing path gains a throw). - renderPhaseId(id) -> `[GSD.02] 05.03-01`; toDir(id, slug) -> `GSD.02-05.03-slug` with a slug guard that sanitizes path-traversal input. - getMilestoneFromPhaseId(phaseId, convention?): READING-B derives the milestone from the `[PROJECT.MM]` prefix, gated on convention === 'bracket' and returning the `vN.0` form (parity with READING-A). The optional parameter keeps the helper pure (no config read) and byte-compatible — every existing single-arg caller resolves to the unchanged READING-A body (ADR Decision 6). - extractPhaseToken(dirName, convention?): bracket dir branch GATED on convention === 'bracket'. A bracket dir `{CODE}.{MM}-{PP}` is string-indistinguishable from the legacy #2043/#1324 letter-prefixed-decimal family (`P0.3-2`, `P0.12-34`) whenever the code ends in a digit, so no string-only discriminator is complete — an ungated auto-detect silently reinterpreted legacy reads on this CRITICAL 6-caller helper. The explicit convention signal keeps every existing convention-less call site byte-identical (pinned by a #2043 numeric-tail characterization in tests/phase-id.test.cjs). - comparator: no new code — comparePhaseNum already orders the dot-decimal `PP[.SS]` tokens extractPhaseToken yields; milestone-qualified ordering is a PR-2 resolution concern (bracketQualifiedKey), not core grammar. - SENTINEL_RANGES / isSentinelPhaseId(phaseId, convention?): {0, 999} non-milestone guard; the bracket-prefix reading is gated the same way (an ungated read called `P0.0-foundation` a sentinel), legacy leading-int form unchanged. - BRACKET_PHASE_TOKEN_SOURCE (dot-or-dash `[.-]` sub-separator; deliberately more permissive than parsePhaseId — a read-tolerance source for PR-2, not the emit grammar) and PHASE_HEADING_PREFIX_SRC exported from the drift-guard-exempt owner so PR-2 builds every bracket read regex from the canonical source and check:phase-id-drift stays green stack-wide. The bracket project code follows the repo's config-validated `[A-Z][A-Z0-9_]*` grammar (not the ADR §1 illustration's `[A-Z]{1,6}`), so every project_code the config permits parses. parsePhaseId has no live callers in PR-1, so this grammar choice is forward-facing for PR-2 with zero PR-1 behavior impact. Tests: tests/adr-612-bracket-grammar.test.cjs (28) — ADR §3 example round-trips, full 5-tuple parse, READING-B (+ legacy-unchanged and sentinel cases), extractPhaseToken bracket ON/OFF, comparator ordering of extracted tokens, sentinel + slug guards, bare-token rejection, exported-source behavioral assertions, and two generative fast-check properties: render∘parse identity over well-formed displays, and the toDir/disk↔display bijection. Plus a #2043 numeric-tail characterization (single- AND multi-digit rows) in tests/phase-id.test.cjs pinning the convention-less reading byte-identical. The compiled gsd-core/bin/lib/phase-id.cjs is gitignored (ADR-457 build-at-publish) and rebuilt by CI, so it is intentionally not committed. Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * chore(#2249): changeset fragment for PR #2258 (docs-exempt: internal grammar behind flag) Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * fix(#2249): reject non-canonical phase-id input + harden toDir (review B1/M1-M3) PR-1 CHANGES_REQUESTED follow-up (epic #612, ADR-612 Decision 4). B1 (blocker): parsePhaseId accepted non-canonical input (unpadded numbers, over-padded numbers, multi-space separators, stray whitespace), so render(parse(x)) === x did not hold for every well-formed x as ADR-612 Decision 4 requires. Both branches now enforce canonicality by construction: parse permissively, rebuild the canonical string via the same emit path (renderPhaseId for display, a hand-rebuilt token for dir/token), and throw "parsePhaseId: not canonical" on any mismatch. The .trim() at the parser's entry is removed — the match anchors now reject leading/trailing whitespace outright, folding into the existing "not a bracket phase id" rejection. M1 (major): toDir only ever guarded the slug; project/milestone/phase/ subphase were interpolated unsanitized, so a hand-built PhaseId (a structural, not nominal, type) could smuggle a path-traversal segment onto disk. Every field is now validated against the exact shape parsePhaseId itself would produce before use. M2 (major): a slug that sanitized to empty (e.g. '!!!') left a dangling trailing hyphen in the emitted dir name. toDir now throws in that case. M3 (major): an all-digit slug (e.g. '2026') was string-indistinguishable from the dir-branch's plan tail, so it silently broke the disk<->identity bijection on read-back. toDir now rejects all-digit slugs. Nits: toDir now rejects a non-string slug instead of coercing it to the literal token 'undefined'/'null'; sentinel boundary tests added for milestones 1/998/1000 (SENTINEL_RANGES is the two discrete values {0, 999}, not an inclusive range — these were already correct, now locked by test). Test-first: every new assertion (concrete examples + fast-check mutation property for B1; concrete cases for M1-M3 and the nits) was written and confirmed red before the implementation changes, per repo TDD convention. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * chore(#2249): reformat changeset body to house convention (review Mi2) The fragment added in ab26190a was a plain paragraph — no bold headline, no trailing issue reference. Reformat to the repo's `**Bold headline** — symptom/explanation. (#issue)` body shape (see e.g. .changeset/agile-pandas-dance.md, .changeset/fierce-pumas-gather.md). Uses (#2249), the issue every commit on this branch references, not the PR number already carried in frontmatter (`pr: 2258`) — the changelog serializer appends `(#{pr})` unconditionally, so a body also ending in `(#2258)` would double-render as `(#2258) (#2258)`. Verified the rendered bullet directly via parseFragment + serializeChangelog: it now reads `... (#2249) (#2258)`, matching the dominant convention across the other fragments (frontmatter pr = merged PR, body reference = originating issue). Also moved the docs-exempt marker back before the paragraph -> after it (matching the file's original order): the marker sits on its own line and is stripped before the body is used, but placing it first left a leading blank line in front of the bold headline once reformatted. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * test(#2249): widen property generators — 3+-digit numerics + subphase-pad mutation (re-review Minor 1/2) PR-1 re-review follow-up (epic #612, ADR-612 Decision 4). Test-only: closes two property-generator coverage gaps the reviewer flagged; no source change (src/phase-id.cts and gsd-core/bin/lib/phase-id.cjs are byte-unchanged). Minor 1 (3+-digit numerics never exercised): numArb capped at 99, so no property fed a 3+-digit milestone/phase/subphase/plan through parse/render/ toDir despite CANONICAL_NUMERIC_RE's dedicated `[1-9]\d{2,}` branch. Widen numArb to 1–999 so the round-trip and disk↔display bijection properties both span 3-digit widths (pad2 passes ≥3-digit values through un-truncated with no leading zero, so canonicality still holds). Add a concrete regression pinning the reviewer's hand-traced example: '[GSD.100] 05' round-trips, renders, and toDirs to 'GSD.100-05-feature' without truncation. Minor 2 (no subphase-pad mutation): the B1 mutation-rejection property covered milestone/phase pad + whitespace mutations but never a subphase pad. Add unpad-subphase / overpad-subphase to the mutation set and a generated `includeSub` boolean that decides whether the canonical carries a `.SS` (forced in for the subphase mutations so there is always a `.SS` to mutate); non-subphase mutations keep their original no-subphase coverage. Non-vacuity verified against the compiled lib by temporarily probing each widened/new property and confirming it fails: round-trip counterexample ["A",100,1,…] and bijection counterexample ["A",1,100,…,"a"] prove 3-digit tokens are genuinely generated and reach the body; a no-op unpad-subphase mutation trips the mutated===canonical guard (counterexample ["A",1,1,1,false,"unpad-subphase"]), proving the subphase branch is reached with a subphase present. Probes reverted; numRuns unchanged. Gates: tests/adr-612-bracket-grammar.test.cjs 44 pass / 0 fail; `npm run test:unit` 1079 pass / 0 fail; `npm run lint:ci` exit 0. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * fix(#2249): consume the #2232 continuation seam at the bracket token's slug-adjacent position (review Major) BRACKET_PHASE_TOKEN_SOURCE was a sixth continuation-recognition site that re-derived the grammar as an unbounded `\d+` literal instead of consuming PHASE_CONTINUATION_SEGMENT_SOURCE, re-opening the #2232 bug class on the bracket path: a PR-2 reader interpolating it over dir `PROJ.01-14-2026-photos-…` (a slug whose first word is a year) over-collected the token as `01-14-2026` instead of `01-14`. Interpolating the cap verbatim at every position was rejected on evidence: the bracket run is `MM-PP[.SS][-LL]` and only the LAST position is slug-adjacent. The exactly-2 cap at the others would under-collect ids toDir itself emits — `PROJ.02-105-slug` (3-digit phase) reads as `02`, `[GSD.02] 05.100` (3-digit sub-phase) as `05` — because CANONICAL_NUMERIC_RE admits `[1-9]\d{2,}` and `[GSD.100] 05` is a pinned regression. Those positions are delimiter- disambiguated (a required field separator; a dot a slug can never contain), not heuristically recognized, so they have no year collision to defend against. Upstream draws the same line for the same reason: core-utils/phase cap the paired PLAN component while the leading phase component stays unbounded. So the run is now positional rather than a free `(?:[.-]\d+)*` repetition, and each position takes the width its delimiter affords: leading unbounded, dash-1 and dot canonical, and the slug-adjacent dash-2 interpolating the single-owner seam. The accepted trade-off is #2232's policy verbatim: a PLAN ≥100 is out of the token grammar. Also derives CANONICAL_NUMERIC_RE from the new BRACKET_CANONICAL_NUMERIC_SOURCE instead of re-spelling it as a literal, so the emit-side gate and the read-side token source are one rule — the same single-owner discipline this fix is about. Behaviour-identical (the anchors make the source's `(?!\d)` guard redundant). Refs #2249 * test(#2249): pin the bracket/#2232 reconciliation — parity surface 6 + divergence gate + property (review Major) The comment block alone cannot hold the divergence: src/phase-id.cts is exempt from the #2128 drift guard by construction, so lint-phase-id-drift.cjs would not catch the bracket token source drifting from the seam. Per the Generative Fix Divergence rule, the divergence is pinned behaviorally instead. Surface 6 joins the existing #2232 parity gate rather than starting a rival one: the review named the bracket token source "a sixth continuation-recognition site", and continuation-grammar-parity.test.cjs is already the invariant-named home where the five #2043 sites agree with the owner on a shared width corpus. Surface 6 asserts the same contract at the bracket run's slug-adjacent position (`01-14-<seg>-photos-…`, mirroring surface 1 with the extra milestone level), so the bracket path now fails the same gate the other five do. A second block pins the DELIBERATE half — the wider canonical width at the delimiter-disambiguated positions, plus the accepted bound (a plan >=100 is out of the grammar). Without it, "unifying" bracket onto the exactly-2 cap would look like a cleanup rather than a regression. The generative property ties the READ side to the EMIT side metamorphically: for every id toDir can produce, BRACKET_PHASE_TOKEN_SOURCE must collect exactly that id's numeric run — no more, no less. It needed a new arbitrary: the existing slugArb generates one [a-z0-9] word and so can never produce the number-leading slug the collision requires. Probe-falsified, both directions (probes reverted): - reverting the source to the old unbounded `\d+` fails 8: the parity gate reports `"01-14-2026-photos-performance" collected "01-14-2026"` — the review's scenario verbatim — and the property shrinks to ["A",1,1,undefined,"100-a"]. - interpolating the seam at EVERY position (the rejected verbatim option) leaves the repro and parity green but fails the divergence gate `'02' !== '02-105'` and the property at ["A",1,1,100,"100-a"] (3-digit sub-phase), which is the evidence that a verbatim cap under-collects ids toDir emits. Width 2 stays green under both probes — the corpus agrees with the owner exactly where the old and new rules coincide, so the gate discriminates rather than merely mirroring the regex. Refs #2249 * docs(#2249): add the new phase-id exports to the CONTEXT.md glossary bullet (round-4 Major) * test(#2249): pin deterministic grammar boundary cases (re-review m1) PR-1 re-review follow-up (epic #612, ADR-612 Decision 4). Test-only: closes the m1 proof gap — the grammar's bounds were exercised only incidentally through the fast-check domain (1-999, [a-z0-9] slugs). No source change (src/phase-id.cts and gsd-core/bin/lib/phase-id.cjs byte-unchanged). Adds a deterministic boundary block (7 describe groups, +22 tests) pinning the compiled lib's CURRENT behavior — a proof gap, not a behavior gap: - m1.1 numeric-width 99/100/101 at milestone/phase/subphase/plan: parse (display + dir) -> render/toDir round-trip byte-equality. The plan position is identity-symmetric (parse/render accept 99/100/101) but toDir drops it (filename-surface dimension only). - m1.2 read-token width is POSITIONAL: BRACKET_PHASE_TOKEN_SOURCE absorbs 99/100/101 at milestone/phase/subphase (delimiter-disambiguated) but caps the slug-adjacent plan (dash-2) at exactly 2 digits — plan >=100 is out of the token grammar (#2232 seam). Pinned as asymmetry, NOT symmetry. - m1.3 leading-zero 007 -> not-canonical rejection at every position/form. - m1.4 slug abuse: parse DROPS a null-byte/control/unicode/emoji trailing slug (never stored, never mis-read as a plan) and rejects a line terminator; toDir's allow-list sanitizer collapses each to a safe [a-z0-9-] token or rejects sanitize-to-empty. - m1.5 absolute-path slug sanitizes (next to the ../../etc traversal test); an absolute-path project on a hand-built id is rejected by PROJECT_ID_RE; an abs-path string is not a bracket id; an abs-path dir slug is dropped to a clean tuple. - m1.6 whitespace-only -> not-a-bracket-phase-id. - m1.7 very-long input (10k) resolves promptly (ReDoS smoke, behavioral): garbage/partial-prefix throw; a 10k-char slug parses (dropped)/sanitizes. No accept-not-reject case is a src bug: parse never STORES an abusive slug (dropped from the identity tuple) and toDir independently re-sanitizes on emit, so the only slug reaching disk is allow-listed. Plan >=100 accepted by parse is the documented positional design (toDir drops the plan; the read-token caps it) — divergence pinned, not papered over. Probe-falsify: corrupted one assertion in each of the 7 groups (m1.4 both its parse-side and emit-side), ran -> 8 distinct named failures, reverted -> 66/66 green. Confirms every new group executes and can fail. Gates: tests/adr-612-bracket-grammar.test.cjs 66 pass / 0 fail; grammar + continuation-grammar-parity + collision-characterization + phase-id family 175 pass / 0 fail; `npm run lint:ci` exit 0. `npm run test:unit` is green except one pre-existing, unrelated env failure (npm-integrity-gate: a live npm-audit advisory in the production dep tree — reproduces with this change stashed; no package.json/lock change here). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-07-24 12:49:53 -04:00
Cody Anderson	612fcb00f7	fix(#2232): cap phase-token continuation segments at exactly 2 digits (all sites) (#2254) ... * fix(#2232): cap phase-token continuation segments at exactly 2 digits (all sites) A phase whose slug's first word is a ≥2-digit number (dir 14-2026-photos-performance, roadmap phase "2026 Photos & Performance" → slug 2026-photos-…) had its phase token over-collected as "14-2026" instead of "14", so every phase-locating verb (init.plan-phase, init.execute-phase, phase-plan-index, state.planned-phase, roadmap.annotate-dependencies) resolved phase_dir=null / plan_count=0 while the directory existed. This is the residual case #2043 explicitly scoped out: its ≥2-digit continuation gate (\d{2,}) distinguishes single-digit slug words but not multi-digit ones (years, counts). The structural distinguisher: getPhaseDirFromPhaseId writes sub-phase and plan continuation segments zero-padded to EXACTLY 2 digits, so a genuine continuation's digit run is exactly 2 — \d{2}(?!\d). The (?!\d) guard caps the run without anchoring what follows, so each call site keeps its own trailing grammar (letter suffixes, dotted sub-phases, boundaries). Shared-source, not hand-synced: the grammar lives once in phase-id.cts as PHASE_CONTINUATION_SEGMENT_SOURCE / isPhaseContinuationSegment (the #2121 single-owner seam), consumed by all five #2043 sites: - phase-id.cts extractPhaseToken (the reported repro) - validate.cts PHASE_TOKEN_FROM_DIR_RE + canonicalPlanStem - roadmap-parser.cts isDirInMilestone numericRe (hyphenated mode) - core-utils.cts + phase.cts extractCanonicalPlanId (paired plan component only — the LEADING phase component keeps unbounded \d{2,}; phase numbers ≥100 are legitimate) Digit-width policy, resolved per triage and locked by boundary tests at 1/2/3/4-digit continuation widths across all sites: sub-phase/plan numbers ≥100 are out of the dir-token grammar. validate.cts phaseDirNameRe's leading \d{2,} is intentionally untouched — it encodes the write-side padding of the leading dir number, not the continuation heuristic, and has no year collision. Fixes #2232 Claude-Session: https://claude.ai/code/session_017KaYUJnfzV3JVVuQnhkcjg * chore(#2232): add changeset for PR #2254 Claude-Session: https://claude.ai/code/session_017KaYUJnfzV3JVVuQnhkcjg * test(#2232): parity gate + fast-check properties for the continuation cap Addresses trek-e's review on PR #2254 (M1, M2, B1). Test-only — the fix itself was verified as a true root-cause fix, so no source changes. M1 — drift/parity enforcement for the new shared constant. scripts/lint-phase-id-drift.cjs guards PHASE_NUMBER_TOKEN_SOURCE only; its TOKEN_DRIFT_RE cannot match a bare \d{2,} re-derivation, so a future edit reintroducing a raw digit-cap at a consuming site would pass lint + CI silently. Extending the lint was rejected: \d{2,} legitimately appears at the intentionally-unbounded LEADING-token sites (validate phaseDirNameRe, core-utils/phase tokenRe), so a textual guard would need sanctions on correct code and would flag by spelling rather than by behaviour. Instead, per the repo's *-parity.test.cjs precedent, added tests/phase-continuation-parity.test.cjs: a shared digit-width corpus (1/2/3/4/5) asserting every consuming surface's notion of "is this segment absorbed" equals isPhaseContinuationSegment(). Covers all five #2043 sites: extractPhaseToken, PHASE_TOKEN_FROM_DIR_RE, canonicalPlanStem, extractCanonicalPlanId (paired component), and roadmap isDirInMilestone (hyphenated mode, on a real ROADMAP fixture). The corpus states the policy independently of the regex, so it fails on divergence rather than mirroring whatever the code does. Failing-first verified: reverting PHASE_TOKEN_FROM_DIR_RE to \d{2,} fails 3 parity tests; reverting the owner constant itself fails 11 across parity + properties + examples. M2 — fast-check properties for the changed parser (4 added to phase-id.test.cjs, following its existing inline fc precedent): - biconditional: a segment is absorbed IFF its digit run is exactly 2 - the owner agrees with observable extraction for every digit run - metamorphic: a write-side getPhaseDirFromPhaseId dir round-trips to its own normalizePhaseName id — ties the cap to the zero-padding convention it mirrors, so a change to the write-side width fails loudly - metamorphic: the round-trip holds when the phase name leads with a year (the #2232 bug itself, generatively) Digit runs are generated as digit strings (not String(int)) so leading-zero forms like "02" — the whole point of the rule — are actually exercised. B1 — GitGuardian red. The session-trailer hypothesis is disproven: the same Claude-Session trailer rides 3 commits now merged to next via #2173, whose GitGuardian check PASSED. GitGuardian's own comment names tests/phase-id.test.cjs:260 — the synthetic dir literal 'M1-14-2026-photos' tripping the generic high-entropy detector. Composed it from parts; the assertion is unchanged, only the source spelling. Refs #2232 Claude-Session: https://claude.ai/code/session_019SkiJk38YWAbmxHrGxEmuU * test(#2232): name the parity gate after the invariant, not the phase module CI caught two failures from the new parity test, both one root cause: lint-test-file-count caps each production module at 2 test files (primary + one integration, per the #3740 consolidation). The file was named phase-continuation-parity.test.cjs, and the linter clusters a test to a production module by name prefix — "phase-*" bound it to src/phase.cts, whose cluster (phase.test.cjs + phase-dependency-levels.test.cjs) was already at the cap, making 3. That tripped the lint-tests job AND the ubuntu-24 unit lane, where tests/lint-test-file-count.test.cjs is a meta-test asserting the linter exits 0 against the real repo. Renamed to continuation-grammar-parity.test.cjs, matching the convention the repo's other cross-cutting parity gates already follow: they are named after the INVARIANT, not a module — capability-precedence-parity, agent-classification-parity, and runtime-launcher-parity all have no corresponding src/*.cts, so they cluster to nothing. The gate tests a grammar shared ACROSS phase-id/validate/core-utils/roadmap-parser rather than the phase module specifically, so the invariant-name is also the semantically correct home. Not allowlisted: a novel offender belongs under the cap, not ratcheted into the exemption list. Content unchanged — same 12 assertions across the same 5 surfaces. Refs #2232 Claude-Session: https://claude.ai/code/session_019SkiJk38YWAbmxHrGxEmuU --------- Co-authored-by: Tom Boucher <trekkie@nomorestars.com>	2026-07-15 15:33:58 -04:00