* fix(#3697): warn when the Requirements line under-selects REQ-IDs
`cmdPhaseComplete` tokenizes ROADMAP's `**Requirements**:` line by splitting
on `[,\s]+` and keeping tokens matching the anchored REQ-ID shape. That is
correct for the canonical comma list the template ships, and silently wrong
for every other form:
`RANGE-01 … RANGE-05` -> the two ENDPOINTS only; the interior IDs are
never considered, yet `requirements_updated`
reports true with zero warnings
`RANGE-01…05` -> ZERO IDs; the whole line is inert
The silence is structural: the only cross-check, `ghostReqIds`, is itself
`citedReqIds.filter(...)`, so an ID the tokenizer dropped is invisible to it
by construction — and to `traceabilityWriteMisses` and `requirements_updated`
with it.
Warn on both paths. This does not add range support: the selected set is
unchanged, so no existing ledger write changes. The trigger is ID-SHAPED
EVIDENCE only — an ID-shaped substring the tokenizer did not select, or a
range operator joining two IDs — with parenthetical citations and HTML
comments stripped before the scan, so the #2334/#2339 over-warning on
`None`, on the shipped `<!-- brackets optional -->` template comment, and on
annotated lines cannot return.
Regression tests extend the #2316/#2334 fixture family in tests/phase.test.cjs
(10 cases: 4 defect, 2 canonical controls, 4 negative-space controls).
Fixes #3697
* fix(#3697): rework under-selection detection onto tokens, not a free-text scan
Round 2, driven by the P4.6 cross-AI review (codex, gpt-5.6-sol) of b3ce71cb.
That review refuted 5 of 9 claims; three were false-positive classes in exactly
the category #2334/#2339 had to REMOVE:
`RANGE-01, RANGE-02 - 3 points` the bare-hyphen alternative read
`RANGE-02 - 3` as a range
`REQ-01, REQ-02 — locked per ADR-7.` the trailing period kept `ADR-7.` out
of the anchored filter, so the
unanchored substring scan reported it
as unparsed
`REQ-01, REQ-02 (see (ADR-7), then ADR-8)`
nested parens left `ADR-8)` behind
Replaces the free-text substring scan + loose range regex with three narrow,
token-based rules (R1 range-shaped token, R2 pure range operator flanked by two
selected IDs, R3 zero-selection with ID-shaped text). Also fixes the review's
CLAIM 9: the warning said IDs were "marked complete" when a ghost range marks
nothing — it now says "selected".
Side effect: the two false NEGATIVES the same review found are now covered —
`RANGE-01 through RANGE-05` and a parenthesised `(plus RANGE-02..RANGE-05)`.
NOT YET DONE (see the handoff prompt): regression tests for the four false
positives, the two new true positives, and the #3697-4 tightening the review's
CLAIM 8 asked for (it currently filters on the warning's phrasing rather than
asserting silence). Verified so far: tsc clean, the 10 existing #3697 tests
green, and a 20-case standalone harness covering every case above.
* test(#3697): pin the v2 token-detector boundary end-to-end
Six new cases + two hardenings for the review findings against v1:
- #3697-1 gains the worded spaced range (`RANGE-01 through RANGE-05`) —
the operator set's `to|thru|through` arm was previously untested.
- #3697-5 (new): a tight range hidden inside balanced parentheses
(`RANGE-01 (plus RANGE-02..RANGE-05)`) warns, names the range token,
and ticks exactly RANGE-01 — the paren shave must not hide it.
- #3697-4 gains the four false-positive classes a free-text detector
produced: numeric estimate (`- 3 points`), date annotation, em-dash
citation with trailing period (`— locked per ADR-7.`), and nested
parenthetical citations.
- #3697-3 and #3697-4 now assert the ENTIRE warnings channel is empty,
not that one phrase is absent — a re-worded over-warning cannot pass.
Negative control: against the merge-base with its lib rebuilt, all 6
defect tests fail and all 10 controls pass.
* fix(#3697): close round-2 review findings — annotation false positives
Round 2 of the adversarial review (against 822a72a04) refuted five
claims; this closes the false-positive class and the cheap misses:
- R1's bare-hyphen arm now demands a full ID on BOTH sides
(`REQ-01-REQ-05`): `LETTERS-\d+-\d+` is also a date-like annotation
(`FY-2026-08`) and a sub-numbered ID, and warning on those is the
expensive class. Tight hyphen shorthand with a live selection is the
disclosed false negative; at zero selection R3 still catches it.
- R2 requires the endpoint pair to imply an INTERIOR (same prefix,
gap > 1): `REQ-02 - REQ-03` selects both endpoints and can drop
nothing, so an annotation hyphen between adjacent IDs stays silent.
- R3 skips placeholder-led lines: `None (per ADR-7)` is a declared-empty
line citing its rationale, not unparsed residue.
- Token shave: quotes/backticks now shaved from alphanumeric tokens
(`` `RANGE-02..RANGE-05` `` warns); punctuation-only tokens get a
bracket-only shave so `(..)` surfaces its operator.
- 256-char token cap bounds the quadratic unanchored substring test.
- Warning text mentions range expansion only when a range rule fired.
Tests: 6 new cases (22 total). Negative control against the merge-base:
8 defect tests fail, 14 controls pass.
* fix(#3697): close round-3 review findings — half-spaced ranges, cross-prefix annotations, markdown wrappers
Round 3 of the adversarial review (against 2eb92dd0e) refuted four
claims; this closes them:
- Half-spaced ranges (`REQ-01 -REQ-05`, `REQ-01- REQ-05`) split at the
tokenizer before R1's `\s*` can see them and under-selected silently.
A glued-fragment rule warns when an operator is glued to a full ID
with an ID-shaped neighbour on the open side and the endpoint pair
implies an interior.
- Cross-prefix pairs around a separator no longer read as ranges:
`REQ-02 - (ADR-7)` and `REQ-02 (...) (ADR-7)` are annotations, and
real ranges are same-prefix by nature. `impliesInterior` now returns
false on prefix mismatch and computes the gap with BigInt (parseInt
lost precision past 2^53).
- The token shave now removes markdown emphasis markers and curly
quotes, so `**None** (per ADR-7)` reaches the placeholder gate and
`**RANGE-02..RANGE-05**` reaches R1.
- The unanchored-substring cap rises to 2048 (a markdown-link range
with a long URL cleared 256); the anchored range regexes scan
linearly and drop their cap.
Tests: 6 new cases (28 total; 377/377 file-wide). Negative control
against the merge-base: 11 defect tests fail, 17 controls pass.
* fix(#3697): round-4 review finding — word operators excluded from glued-fragment rule
`TOREQ-05` is a valid prefix-agnostic REQ-ID, and the glued-fragment
rule read it as `to` + `REQ-05`, warning on the canonical two-ID list
`REQ-01, TOREQ-05`. Glued fragments are now SYMBOL-operator-only
(`..`+, ellipsis, dashes): a word operator glued to an ID is an ID,
not a range spelling.
Tests: word-operator-prefixed ID control (misparse channel silent; the
fixture's ghost-ID warning legitimately fires, so the whole-channel
assertion stays with the registered controls) and an underscore-wrapped
tight-range defect case. 30 targeted cases; 379/379 file-wide; negative
control: 12 defect tests fail on the merge-base, 18 controls pass.
* fix(#3697): round-5 review findings — trailing word-op glue, dot shave, honest wording
- The glued-fragment TRAILING arm takes the word operators back: an ID
must end in digits, so `REQ-01through` can never be an ID — the
round-4 TOREQ collision was leading-arm-only, and symbol-only on both
arms lost the `REQ-01through REQ-05` typo class.
- A trailing run of 2+ dots survives the punctuation shave: `REQ-01..`
is a glued range operator, not sentence punctuation, and the shave
was silently eating the `REQ-01.. REQ-05` form.
- The warning now says the line "could not be parsed as" a
comma-separated REQ-ID list: `**REQ-01**, **REQ-05**` IS such a list
— the selector just cannot parse decorated tokens — and a warning
that misstates the input teaches readers to distrust it.
Tests: two new trailing-glue defect cases (32 targeted; 381/381
file-wide). Negative control: 14 defect tests fail on the merge-base,
18 controls pass.
* test(#3697): use t.after for cleanup per CONTRIBUTING test ruleset
CONTRIBUTING bans try/finally inside test bodies (it masks failures);
the approved shape is `t.after(() => cleanup(tmpDir))`. All seven
converted tests are this PR's own additions; the file's pre-existing
instances are untouched.
* chore(#3697): add changeset fragment for the Requirements-line under-selection warning
changeset-lint fails on this PR (fail_missing_fragment): src/phase.cts is a
user-facing surface and the branch carried no .changeset/*.md. Adds the Fixed
fragment via `npm run changeset -- --type Fixed --pr 3744`, symptom-led per
the house format, with the (#3697) backlink.
* refactor(#3697): extract the Requirements-line detector to a testable surface
Round-3 review Blocker 1 requires a fast-check property test over this
detector (`RULESET.TESTS.property-based-testing`: modules implementing
parsing contracts must include at least one), and Blocker 2 requires
limit-1/limit/limit+1 fixtures on its 2048-char token cap
(`RULESET.TESTS.boundary-coverage.fixtures`). Neither is expressible while
the logic is a closure inside `cmdPhaseComplete`: every existing #3697 test
reaches it by spawning the CLI, and a property test cannot pay a subprocess
per generated case.
So the selector and the three detection rules move to module scope as
`analyzeRequirementsLine` (pure, exported) plus
`formatRequirementsLineWarning`, and `cmdPhaseComplete` calls them. This
commit changes NO behaviour: `tests/phase.test.cjs` is untouched here, and
the pre-round suite passes against it unmodified (403/403).
Two things the move makes explicit rather than incidental. The selector and
the detector tokenize the SAME line DIFFERENTLY — the selector strips only
`[` and `]`, the detector also shaves quotes, emphasis and trailing sentence
punctuation — and that gap is deliberate: it is why `ADR-7)` is not selected
while `ADR-7` is still nameable in a warning. They now sit adjacent with the
reason written down, so they cannot drift apart silently.
And the stale citations in the moved comment are corrected. It pointed at
src/phase.cts:833,920,1078 for the `**Requirements**: TBD` seeds, which had
drifted to 1132/1237/1413, and at `templates/roadmap.md:32`, which is
`gsd-core/templates/roadmap.md:32`. Both are now anchored by content.
* fix(#3697): stop the warning claiming a misparse that did not happen
Round-3 review Major 3 and Minor 4. Both are the same defect: the warning
asserted more than the evidence supported.
MAJOR 3 — a correct comma list such as `RANGE-01, RANGE-02 — RANGE-05
deferred` warned "could not be parsed ... Range forms are not expanded;
rewrite the line". Reproduced: it selects RANGE-01, RANGE-02 AND RANGE-05,
i.e. every ID written on the line. Nothing was dropped, and the pinned
control only stayed silent because its pair was ADJACENT (gap == 1), so the
control was passing by accident of the fixture rather than by the rule.
The obvious fix — go silent — is not available. `RANGE-02 — RANGE-05` as a
range and as an annotation separator are textually identical, and no
token-level rule separates them; staying quiet re-opens the exact silent
under-selection #3697 is about. Deciding the ambiguity by assertion in
either direction is wrong. So it is DISCLOSED: the warning now has two
channels, chosen by whether any ID-shaped token was actually left unselected
(`droppedIdShaped`).
* something was dropped (tight range, glued fragment, inert residue)
-> "could not be parsed as a comma-separated REQ-ID list", as before.
* nothing was dropped (only the spaced-operator rule fired)
-> "contains what reads as a range between two cited REQ-IDs", stating
both readings and saying explicitly that an annotation separator means
the line is already correct.
This retires the "could not be parsed" wording for the four #3697-1 spaced
cases too, and that is a deliberate expectation change rather than a fix
counted twice: those lines never failed to parse either. They still warn,
still name the selected IDs, and still assert the endpoint-only marking is
unchanged; #3697-1 now also asserts the misparse channel stays SILENT.
MINOR 4 — `Deferred (see ADR-7)` reported `Unparsed text: ADR-7`, naming a
citation as requirement content it had failed to read. The trigger is
correct and stays: #3697's acceptance criterion asks for a warning "when it
selects zero IDs from a line that is non-empty and is not the `TBD`
placeholder", and inferring placeholder-ness from arbitrary prose is the
free-text heuristic this detector exists to avoid. What was wrong is the
wording, so the non-range arm now says "ID-shaped text that was not
selected" and names the escape the author actually has (`TBD` / `None`).
Tests: #3697-9 (three spaced forms — must warn, must NOT claim a misparse,
must offer both readings) and #3697-10 (`Deferred (see ADR-7)`, `N/A
(tracked in ADR-12)` — must warn, must not say "Unparsed text", must not
diagnose a range, must name the placeholder escape).
Reversion control: reverting the ambiguous channel fails #3697-9 (3 named
tests); reverting the R3 wording fails #3697-10 (2 named tests).
* fix(#3697): cap every token predicate, complete the dash set, cover the boundary
Round-3 review Blocker 2 and Nit 6, plus one self-found finding. All three
are about the detector's own predicates, so they land together.
BLOCKER 2 — the 2048-char budget had no boundary coverage.
`RULESET.TESTS.boundary-coverage.fixtures` requires limit-1 / limit /
limit+1 for any budget parameter. #3697-B1 and #3697-B2 now exercise 2047 /
2048 / 2049 against BOTH predicate families the cap guards, and each asserts
its fixture's exact length before asserting behaviour, so a mis-built
fixture fails loudly rather than passing at the wrong size. Clause (d) of
that rule — an input pushed within reserve-distance of the limit — has no
referent here: this is a hard cap with no reserve constant beside it, and
the test comment says so rather than leaving the omission to be re-derived.
NIT 6 — the cap guarded only the unanchored ID-substring regex. The
anchored range regexes were left uncapped, justified by a comment asserting
they scan linearly. The finding is right that this is informational (they
are anchored; the input is a local ROADMAP.md), but an asserted property is
cheaper to enforce than to defend, so all three predicates now share one
`short()` guard. #3697-B2 is what pins it: at 2049 the anchored scan must
now decline to classify.
SELF-FOUND (RV4 guard-shape census) — the range-operator set is a list this
code fixes at author time over a domain that grows without it, so the round
owes a census of what the enumeration reaches.
reached: `..`+, U+2026, U+2013, U+2014, ASCII `-`, to/thru/through
NOT reached: U+2010 hyphen, U+2011 non-breaking hyphen, U+2012 figure
dash, U+2015 horizontal bar, U+2212 minus sign
consequence: a range spelled with any of those is SILENTLY under-selected
— #3697's own defect, in the code that exists to fix it
Those five close. They are the same operator at a different codepoint and
carry none of the ASCII hyphen's collision risk, because they are not the
REQ-ID separator: `FY-2026-08` is date-shaped only with ASCII hyphens, so a
U+2010 never reaches the ID shape. They therefore join the NOHYPHEN arm
beside `—` and `–`; the strict full-ID-both-sides shape the bare hyphen is
held to is untouched, and #3697-12 pins that.
Still NOT reached, declined with reason rather than left unstated: `→`, `~`,
`..=`, `..<`, `until`, and `up to` (two tokens, so never one operator
token). Each is a symbol or word with an independent non-range use between
two REQ-IDs — the over-warning class #2334 cost three rounds.
Reversion control: reverting the uniform cap fails #3697-B2 (limit+1);
reverting the dash set fails #3697-11 (5 named tests).
* test(#3697): add the fast-check property coverage the parser rule requires
Round-3 review Blocker 1. `RULESET.TESTS.property-based-testing` (CONTEXT.md)
requires modules implementing parsing contracts to carry at least one
fast-check property test asserting a domain invariant, and the round-2 diff
had zero occurrences of `fc.` across its +311 test lines. Five properties,
1,900 generated cases:
P1 soundness of silence (boundary containment) — for ANY canonical comma
list of well-formed REQ-IDs, the selected set EQUALS the written set
and nothing warns. This is the #2334 over-warning invariant and the
#3697 under-warning invariant asserted as one statement, over
generated IDs rather than hand-picked ones. It generalises #3697-4b:
a prefix beginning with a word operator (`TORANGE-05`) is an ID, and
P1 covers that class rather than the single example.
P2 completeness — a same-prefix pair with an interior between them,
separated by any of the nine spaced operators, ALWAYS warns.
P3 the #2334 invariant — an ADJACENT pair around a separator can drop
nothing, so it stays silent however it is annotated.
P4 totality + idempotency — total over arbitrary strings, deterministic,
and the formatter agrees with the analysis on whether there is
anything to say (a warn with no text, or text with no warn, is a
channel that can go silent or noisy on its own).
P5 containment — every selected ID is ID-shaped and appears verbatim in
the input.
Honest scoping, since a property test is easy to overclaim: P1, P3, P4 and
P5 hold against the round-2 code as well as this one — they are regression
guards, not bug-finders, and their value is that the invariants are now
stated and generatively checked rather than implied by examples. P2 is the
one that would have failed before the dash enumeration was completed.
fast-check v4 removed `fc.stringOf`, so the ID-prefix tail is built from
`fc.array(...).map(join)` with the alphabet pinned to the selector's own
`[A-Z0-9]` class.
These live in tests/phase.test.cjs rather than a new
`phase.property.test.cjs`: `lint-test-file-count` caps a production module
at 2 test files and phase.cts is already at its allowlisted entry, so a new
file would trade one gate for another.
* docs(#3697): document the ROADMAP Requirements-line grammar
Round-3 review Minor 5 — the change adds net-new user-visible warning output
for a grammar constraint documented nowhere under docs/. `type: Fixed` is
docs-exempt so this does not block, but a warning about a rule the reader
cannot look up is not actionable, and that is worth fixing whether or not a
gate demands it.
Added as a subsection of `phase complete` in docs/CLI-TOOLS.md, beside the
existing SUMMARY artifact-check advisory it is a sibling of: the supported
comma-list form, why ranges are deliberately not expanded, that `TBD` and
`None` are the entire placeholder vocabulary, and what each of the two
warning voices means — including that the range/annotation one may be
reporting a line that is already correct.
Existing file rather than a new one, deliberately: docs/ carries generated
indexes and zh-CN / ja-JP trees, and a new top-level page invites a parity
or index gate this change has no reason to touch.
* fix(#3697): rule-scope the warning-channel discriminator
Self-found at the round's pre-push review, against the Major 3 fix two
commits back. That fix chose the channel from a LINE-GLOBAL question — "was
any ID-shaped token left unselected?" — while the rules that produce the
warning are not line-global. The two disagree as soon as the line carries an
ID-shaped token no rule fired on:
`RANGE-01, RANGE-02 — RANGE-05 deferred per (ADR-7)`
`(ADR-7)` survives the selector's bracket strip, so the global test called it
a drop and sent the line to the assertive channel — putting the false "could
not be parsed ... rewrite the line" claim back on a correct line. That is
review finding Major 3 returning through a side door, and it directly
contradicts #3697-4, which pins a parenthetical citation as NOT unparsed
residue.
The discriminator is now rule-scoped: R2 is the only ambiguous rule, so the
ambiguous channel requires that R2 fired, that no other rule did, and that
every endpoint R2 fired on was actually selected. The last conjunct is not
redundant — the detector shaves brackets and the selector does not, so R2 can
fire on a `(RANGE-02)` that was never selected, and that IS a drop:
`RANGE-01 (RANGE-02) — RANGE-05` -> assertive, correctly
`droppedIdShaped` is replaced by `spacedRangePairs` (R2's hits, so the
channel can ask about the endpoints the rule fired on) and the
`rangeReadingOnly` verdict.
Reversion control: against the line-global rule, #3697-9b fails. #3697-9c
passes under both rules — there the dropped token IS the R2 endpoint, so the
two agree; it is a regression guard, not a bug-finder, and is recorded as
such rather than counted as a second control.
* fix(#3697): hold every dash to the strict range shape, not just ASCII
Self-found at the round's pre-push review, and it CORRECTS a claim made two
commits back. That commit widened the range-operator set by five Unicode
dashes and asserted they "carry none of the ASCII hyphen's collision risk,
because they are not the REQ-ID separator". That reasoning was wrong. The
collision is a property of the SHAPE — `PREFIX-\d+ <dash> \d+` is also a date
(`FY-2026-08`) and a sub-numbered ID (`API-2-01`) — and the shape does not
care which dash sits in the operator slot, because the ID's own separator is
still ASCII either side of it. Measured:
RANGE-01 (target FY-2026-08) silent <- pinned by #3697-4
RANGE-01 (target FY-2026‐08) WARNED <- same line, U+2010
So the widening reintroduced the #2334 over-warning class on a date
annotation. It also exposed that the inconsistency PREDATES this PR: U+2013
and U+2014 were already in the loose arm at ce71dd399, so the en- and em-dash
forms of that same date annotation warned before round 3 ever ran.
One rule for every dash: a tight range spelled with any of the eight must
carry a FULL ID on both sides, exactly as the bare hyphen already had to.
`..`, `…` and the word operators stay loose — no date or sub-number reading
exists between two numbers, so the strict shape would cost them coverage for
nothing.
The cost is a false negative, and it is one the design already accepts:
`RANGE-01, RANGE-02-05` is silent today, deliberately, and now
`RANGE-01, RANGE-02–05` is too. That removes an inconsistency rather than
opening a gap, and a bare `RANGE-02–05` still warns — it selects nothing, so
R3 catches it.
Tests: #3697-13 (date annotation AND sub-numbered ID silent for all eight
dashes), #3697-13b (full-ID tight range still warns for all eight),
#3697-13c (loose operators keep their numeric endpoint), #3697-13d (the
accepted false negative is symmetric, and the bare zero-selection line still
warns).
* fix(#3697): close the round's own pre-push review findings
An adversarial cross-AI review of this round refuted 4 of its 10 claims. All
four were real. Every fix below is to code THIS round introduced.
1. THE SOFT VOICE CLAIMED TOO MUCH (refuted CLAIM 1).
`REQ-01, (REQ-02), REQ-03 — REQ-05` took the range-reading voice and told
the author "the line is already correct and nothing needs to change" — while
`(REQ-02)` had been dropped by the selector, which does not strip
parentheses.
The channel choice is still right, and deliberately so: `(ADR-7)` and
`(REQ-02)` are the SAME shape, so routing on "was anything unselected?" puts
the false "could not be parsed" claim back on a line carrying a citation —
the misroute fixed two commits ago. No rule can adjudicate this; the author
can. So the voice stops asserting the line is correct (it now speaks about
the SEPARATOR, which is all it has evidence about), and BOTH voices gained a
factual clause naming ID-shaped text the selector skipped, with the reason
(brackets are not stripped) and no verdict attached.
2. THE CAP SILENCED A LINE THAT USED TO WARN (refuted CLAIM 2).
A 2049-char range token warned before this round and went silent after it:
the "uniform cap" commit bounded the predicate and, with it, the warning.
That is #3697's own defect, introduced by the fix for a nit.
The cap bounds the WORK, not the warning. An over-cap token carrying `-` is
now recorded as unclassified (a linear `includes`, never the unanchored
regex the cap exists to keep off it) and gets its own voice: "could not be
checked ... the REQ-ID selection on this line is unverified". Unclassified
is reported, never treated as clean.
3. THE CAP WAS NOT UNIFORM (review MISSED finding).
R2 capped the operator token but not its neighbours, so
`<2049-char ID> .. <2049-char ID>` still ran REQ_ID_SHAPE_RE and BigInt over
both endpoints unbounded. The glued rule had the same hole. Every
participant is capped now.
4. PROPERTY P5 WAS VACUOUS (refuted CLAIM 5).
It drew from a bare `fc.string()`, which over 500 samples produced max
length 10 and ZERO inputs containing a REQ-ID — the loop body never executed
an assertion. A containment property that never contains anything is a green
test measuring nothing. The generator now interleaves real IDs with noise
and the property ASSERTS it saw them (>50/500), so it can never silently go
vacuous again. The free-form coverage it was actually providing survives,
honestly labelled, as #3697-P6.
The same finding refuted this round's claim that P2 distinguishes pre-round
behaviour: every operator P2 uses was already in the pre-round operator set.
P2 is a regression guard, and its comment now says so.
Also: docs/CLI-TOOLS.md repeated the broken channel claim verbatim (review
MISSED finding) and is corrected with the code.
Tests: #3697-9d (soft voice names the skipped ID, never claims the line is
correct), #3697-9e (over-cap token reported as unclassified, still warns),
#3697-9f (R2 and the glued rule cap their neighbours). #3697-B1/B2 now key the
boundary on the PREDICATE's verdict with `warn` asserted true at every length —
asserting `warn === false` at limit+1 was itself finding 2.
* docs(#3697): describe the third voice and the dash rule
Follow-on to the review-findings commit: that commit corrected the docs' claim
about the soft voice but left two things the code now does undescribed.
- There are THREE voices, not two. The over-cap voice ("could not be checked
... unverified") arrived with the fix for the review's CLAIM 2 and had no
entry.
- Dash spellings require a full ID on both sides, and `..` / `…` / the word
operators do not. That asymmetry is deliberate and load-bearing —
`PREFIX-<digits><dash><digits>` is date- and sub-number-shaped — so a reader
hitting `REQ-01-05` and getting silence has no way to find out why. The
accepted cost (`REQ-01, REQ-02-05` unreported, bare `REQ-02-05` still
reported) is stated rather than left to be discovered.
Documentation only; no behaviour change.
* fix(#3697): close the continuation review's findings
A continuation of the same adversarial reviewer, run against the reworked
round, refuted 6 of 7 claims. Four were real defects in this round's own work
and are fixed here; the other two are answered rather than changed, below.
1. THE SKIPPED-TEXT CLAUSE WAS ON ONE VOICE, NOT BOTH (refuted CLAIM A).
The previous commit's message said both voices gained it. Only the soft
return appended it. The assertive voice now carries it too — and, because
that voice already names range tokens and inert residue under its own
clauses, the note is filtered to what those did not already name. A warning
that says the same token twice is one readers learn to skim.
2. THE CLAUSE'S WORDING WAS FALSE (also CLAIM A).
It read "brackets and parentheses are not stripped". Square brackets ARE
stripped by the selector — `[REQ-01, REQ-02]` is the documented form — so
only parentheses qualify. Corrected in the message and in docs/CLI-TOOLS.md,
which had inherited the same error.
3. THE OVER-CAP RULE STILL SILENCED A LINE (refuted CLAIM B).
`oversizedTokens` filtered on `includes('-')`, which misses an over-cap
OPERATOR: `REQ-01 <2049 dots> REQ-05` warned before this round, R2 declined
to classify it once capped, and nothing reported it. That is the exact
regression the field was added to close, one input over. Any token past the
cap now counts — what it contains is irrelevant when we could not read it.
4. AND THEN OVER-REPORTED ONE (review MISSED finding).
With (3) in place, a 2049-character CANONICAL REQ-ID was selected by the
uncapped, fully-anchored selector AND flagged "REQ-ID selection on this line
is unverified" — a contradiction inside one warning. A token the selector
took was examined end to end, so it is excluded.
Two findings are answered, not changed:
CLAIM C — the selector's own `REQ_ID_SHAPE_RE.test` is uncapped. True, and
deliberate: this round does not touch what gets MARKED, and the pattern is
anchored at both ends with no nested quantifier, so it is linear. The claim
that "all predicate paths are capped" was too broad; the DETECTOR's are.
CLAIM E — `REQ-01, REQ-02<dash>05` is silent for every dash. That is the
documented, deliberate cost of holding dashes to the strict shape, and it is
symmetric with ASCII, which behaved that way before this PR. The reviewer is
right that "without losing a range spelling that should be detected" was too
strong; a bare `REQ-02<dash>05` still warns.
Tests: #3697-9g (clause on the assertive voice, no repetition, bracket claim
true), #3697-9h (over-cap operator does not silence the line), #3697-9i (a
selected over-cap ID is never called unverified). #3697-9f is rebuilt — its
first version used the SAME id twice, so R2 could not have fired even uncapped
and it proved nothing; it now uses endpoints with a gap and fails when the
neighbour cap is removed.
Reversion control: all four fixes fail a named test when reverted in isolation
(#3697-9h, #3697-9i, #3697-9g, #3697-9f).
* fix(#3697): scope the over-cap exemption to what could actually pair
A second continuation of the same reviewer, against the reworked round,
confirmed the two claims that matter most and refuted three. This closes the
one real defect; the other two are answered below.
CLAIM J / CLAIM K (one defect, found from both directions). The previous
commit exempted EVERY selector-accepted token from `oversizedTokens`, on the
reasoning that the selector is uncapped and anchored so it examined the whole
token. True of that token's SELECTION — and not the same as "no rule was
suppressed by it". Two over-cap valid IDs either side of `..` are both
selected, so both were exempted, and R2 is capped: a line that warned before
this round went silent.
That is the third appearance of one class in this round — the cap suppresses a
check, and the suppression is not reported. Each fix for it over-corrected in
the opposite direction, which is why the rule is now stated in terms of what
was actually suppressed rather than in terms of the token: an over-cap token is
exempt only when it was selected AND nothing beside it could have paired with
it into a range (no range operator, no glued fragment, no second over-cap
token). Everything else is unexaminable and says so.
Two findings are answered, not changed:
CLAIM M — the reviewer demonstrated, with driven evidence, a contextual rule
that catches `REQ-01, REQ-02-05` while leaving `FY-2026-08` and `API-2-01`
silent: recognise `PREFIX-a<dash>b` only when another SELECTED id on the line
shares that prefix. That refutes this round's claim that the strict-dash
trade was FORCED, and the claim is withdrawn — it is a design choice. The
choice stands for this PR: the conservative rule is what ASCII already did
before #3697, adopting a new contextual heuristic unreviewed at the end of a
round is how the last three defects in this round were made, and #3697 asks
for a warning rather than better range inference. Named here so the
alternative is on the record rather than lost.
Docs MISSED — CLI-TOOLS said every token over 2,048 characters "is not
classified at all" and warns. Selection is not bounded; only range detection
is. Corrected.
Confirmed by the same pass, and worth recording because they are the PR's
load-bearing promises: a 20,000-input comparison of the pre-extraction selector
against HEAD found `mismatches=0` (nothing about which REQ-IDs are MARKED has
changed), and the uncapped selector regex was measured linear from 100k to 800k
characters.
Tests: #3697-9f now asserts the range case is reported rather than silent, and
#3697-9j pins the exemption's scope in both directions. Reversion control:
restoring the blanket exemption fails both.
* fix(#3697): warn on zero selection, as the acceptance criterion asks
`Deferred`, `N/A`, `Pending`, `TBA` and `-` selected no REQ-IDs and stayed
SILENT, while three shipped artifacts said they warned: `docs/CLI-TOOLS.md`,
the `placeholderLed` census comment, and the advice string the command emits
to the user. The asymmetry was the tell — `Deferred (see ADR-7)` warned,
because the citation supplied the ID-shaped residue R3 required, while bare
`Deferred` did not. The claim was written into three places and never
executed once.
This is also #3697's AC-1b/AC-4 verbatim: "warn when `citedReqIds.length ===
0` while the raw capture is non-empty and not `TBD`".
R3b keys on the SELECTION being empty, never on what the prose means, so it
adds no free-text heuristic. It is deliberately not gated on ID-shaped
residue the way R3 is, and the negative space is what settles that: all
fifteen #2334/#2339 fixtures are held silent by non-zero selection or by
`placeholderLed`, and not one of them by the ID-shape gate — measured, not
argued. The gate was buying no negative space while costing the acceptance
criterion.
`tokens.length > 0` keeps an empty line and a comment-only line silent: the
tokenizer strips `<!-- ... -->` before splitting, so the shipped template's
own comment cannot reach the rule.
Selection behavior is unchanged. This warns; it never invents an ID.
Also extracts `warn` to a named const (round 3 review Minor 3) — this commit
adds a disjunct to exactly that predicate, and in the return literal a later
reordering would be a TDZ ReferenceError rather than a reader-visible error.
Tests: #3697-14 (six zero-selection lines warn and tick nothing, and the
warning names the TBD/None escape), #3697-14b (five placeholder spellings
stay whole-channel silent), #3697-14c (comment-only line stays silent).
Fail-first controls: all six #3697-14 cases fail against the pre-fix tree;
-14b and -14c pass at both ends, which is correct — they pin silence the
widening must preserve.
* fix(#3697): name the REQ-ID a glued delimiter dropped
`RANGE-01; RANGE-02` selects only RANGE-02 and marks only RANGE-02, with
`requirements_updated: true` — #3697's own half-success failure mode, reached
by one wrong delimiter, and silent before this rule. It is the issue's AC-1a
("a warning whenever the line contains ID-shaped content that the tokenizer
did NOT select") at the shape most likely to be typed by accident.
Round 4 review rated this Major rather than Blocker on the ground that the
case is indistinguishable from a parenthesised citation, since `(ADR-7)` also
shaves down to a bare ID. At the RAW token level it is distinguishable, and
that is what makes the rule shippable: `REQ-01;` is shaved of a trailing
DELIMITER, `ADR-7)` of a citation wrapper. R4 keys on that shave class and
requires the token to sit outside any parenthetical.
Measured before implementing: 0 false positives and 0 false negatives across
21 probes, including all fifteen #2334/#2339 negative-space fixtures. A first
cut without the parenthetical test scored 3 false positives — every one of
them a colon inside a citation (`(see ADR-7: section 3)`) — which is why that
test is the rule's boundary rather than an optimisation.
Adds the delimiter census the module did not have. The range-operator domain
was already censused; the comma-substitute domain was not. Swept 26
spellings: exactly two produce a silent under-selection, `; ` and `: `. Every
other spelling either selects both IDs or selects none and already warns. The
review hand-listed the semicolon; the colon is the sibling that sweep found,
and it fails identically.
`rangeReadingOnly` now excludes an R4 hit — the ambiguous voice claims nothing
was dropped, and must not speak for a line where something demonstrably was.
Tests: #3697-15 (four delimiter shapes warn, name EVERY dropped ID, and tick
exactly the unchanged selection), #3697-15b (three citation forms stay
whole-channel silent). Fail-first control: all four #3697-15 cases fail
against the previous commit's tree; -15b passes at both ends, pinning the
boundary the widening must not cross.
* fix(#3697): give the Requirements-line warning a stable machine kind
The warning's kind existed only in the prose of its message, so every consumer
and every test had to regex an English sentence — and rewording a message
silently un-asserted the tests that pinned it. Round 4 review Major 3.
The repo already had the settled seam for exactly these semantics.
`CONTEXT.md` records `diffLiveConfig` emitting `kind:'unverified'` for a
truncated scan, which is precisely this module's third voice; and
`WAVE_CLEANUP_WARNING` in `src/worktree-safety.cts` carries codes for the same
reason. ADR-3473 Decision 3 ("failure is a value") points the same way.
`formatRequirementsLineWarning` now returns `{ code, message }` instead of a
bare string, which also settles round 4 Nit 3 — `null` still means CLEAN, a
legitimate value, but the success arm is no longer a naked string one field
away from the shape the ADR standardises on.
The kind is carried ALONGSIDE the prose, never instead of it. `warnings[]` is
a documented `string[]` in `phase complete`'s JSON output, rendered by
execute-phase.md's "If has_warnings is true" step, so re-typing its elements
would be a breaking output-contract change for a shipped command. The code is
emitted as its own additive `requirements_line_warning` field, absent
entirely when the line is clean.
Vocabulary, exported so tests key on it rather than on string literals:
`req-line-misparse`, `req-line-range-reading`, `req-line-unverified`.
Tests: channel ROUTING in #3697-9/-9b/-9c/-9d/-9e/-9g/-10 now asserts the code;
message-content assertions stay where the user-visible wording is itself under
test. #3697-16 pins the code end-to-end through the CLI's JSON for four line
shapes and asserts warnings[] is still a string[]; #3697-16b pins that a clean
line emits no kind at all, because a field present on every run carries no
information. #3697-P4 holds kind-and-message-appear-together and
kind-is-in-the-declared-vocabulary over arbitrary input, so a channel added
later cannot ship without one.
* test(#3697): pin the divergence against the second parser of the same line
CLAUDE.md, KNOWN DEFECTS & ANTI-PATTERNS: "Generative Fix Divergence: when
sharing constants/arrays/parsers between parallel surfaces, add a parity
assertion test that fails if they diverge." Round 4 review Major 2.
`normalizePhaseReqIds` (src/gap-checker.cts) parses the SAME ROADMAP
`**Requirements:**` value — its own docblock says callers "may pass the
roadmap value through verbatim" — and diverges on four axes. Measured, not
inferred:
line phase complete gap-checker
RANGE-01..RANGE-05 [] 5 IDs
None (per ADR-7) [] ["ADR-7"]
(REQ-02) [] ["REQ-02"]
REQ-01a [] ["REQ-01a"]
REQ-01, REQ-02 both both
This pins the divergence rather than removing it, which is the review's
second option and the correct one here: unifying the two would change what
`phase complete` MARKS, and "the ledger-writing set is byte-identical to base"
is the one invariant this PR holds fixed. Every axis is now asserted in BOTH
directions, so drift on either side fails here instead of widening silently.
The range axis is a DELIBERATE disagreement and is labelled as such — #3697
declines range expansion in terms ("I am not asking for range syntax to be
supported") while gap analysis adopted it under #1269.
The placeholder axis is the one worth reading twice: `None (per ADR-7)` is a
declared-empty line to `phase complete`, which reads the lead token, and a
one-requirement line to gap-checker, which strips parentheses first so the
citation survives its ID-shape filter. That is a citation being reported as a
requirement.
#3697-17b states the cost concretely: one line, five requirements in scope to
gap analysis and zero to phase complete. This PR is what makes that
contradiction visible, by finally giving the silent side a voice.
* fix(#3697): stop the skipped-text rider reporting a date, and close the 4b channel gap
Two round 4 review minors, both about a warning saying something it cannot
support.
MINOR 2 — false rider content. `REQ_ID_SUBSTRING_RE` is unanchored, so
`FY-2026-08` matches as `FY-2026` and lands in `unselectedIdShaped`.
`REQ_RANGE_TOKEN_RE`'s entire strict-dash arm exists to keep that shape
silent, and #3697-4 pins `RANGE-01 (target FY-2026-08)` as producing no
warning at all — but whenever some OTHER rule fired on a line that also
carried a date annotation, the rider told the author to "check whether any of
it is a requirement" about a date. Not a false warning, since the line was
warning anyway; false CONTENT, in the #2334 voice, through the side door.
Filtered at the MESSAGE rather than in the analysis: `unselectedIdShaped`
stays a faithful record of what the selector skipped — it is documented as a
fact that never routes — while the user-facing clause declines to assert
requirement-ness about a shape the design already ruled unadjudicable.
#3697-18b is the other half, so the filter cannot become a silencer: a
genuinely dropped REQ-ID is still named.
MINOR 1 — `#3697-4b` asserted only that the ASSERTIVE channel stayed silent,
so a regression routing `RANGE-01, TORANGE-05` into the AMBIGUOUS channel
would have passed. Whole-channel silence is not available on that fixture (the
pre-existing ghost-ID warning legitimately fires on the unregistered
`TORANGE-05`), so the precise assertion is that no Requirements-line warning
of ANY kind was emitted. The machine code added earlier in this round is what
makes that statable; before it, "both channels" could only have meant a second
prose regex.
* docs(#3697): record the Requirements-line seam in CONTEXT.md
CLAUDE.md names the CONTEXT.md glossary as a PR gate, and
`get_cochange_context(src/phase.cts, 45d)` ranks CONTEXT.md 4th at 25
co-changes — above src/init.cts and src/roadmap.cts. This PR introduced a
named seam, three warning kinds, a bound, a rule taxonomy and a deliberate
cross-parser divergence, and recorded none of it. Round 4 review Major 4.
The precedent is explicit rather than inferred: the directly analogous seam
is already there as `LIVE-CONFIG.GUARD.SEAM.truncation`, including its bound
and its boundary obligation — and that entry is the one this module's third
voice was modelled on.
Eight predicates, in the machine-oriented section beside it:
.module the two exported functions and the code vocabulary
.selector-identity citedReqIds is byte-identical to base and is the
only thing reaching the ledger — a change to what
phase.complete MARKS is outside this contract
.rules R1 / R2 / R2' / R3 / R3b / R4 / over-cap
.kinds the three codes, and why they ride beside
warnings[] rather than inside it
.cap 2048, neighbours included, and the boundary rule
.placeholder the gate that actually holds the negative space
.census-domains both open domains with their NOT-reached members
.gap-checker-divergence the four axes, pinned not unified
The changeset type is `Fixed`, which exempts this PR from the docs/
co-change requirement — but the glossary gate is separate from that
exemption, and the 2048 cap in particular is a machine-canon-shaped fact
that until now existed only inside a source comment.
`docs/CONTEXT-INDEX.json` regenerated (269 predicates); lint:generated-sync
confirms all six targets in sync.
* docs(#3697): document what the command now does, in one changeset sentence
DOCS. The grammar section predated this round's two new rules, so it
under-described the behaviour it exists to make lookup-able:
- The placeholder paragraph enumerated three words; the rule is a DEFAULT.
Any wording that selects no REQ-IDs warns, and the placeholders are matched
as the LEAD token, so `None (per ADR-7)` and `**None**` are declared-empty
too. The comment-only line is called out, because "any other wording" would
otherwise read as covering the shipped template's own `<!-- ... -->`.
- The comma rule was implicit. `REQ-01; REQ-02` marks only REQ-02, and it is
the quietest way to lose a requirement on this line — `requirements_updated`
reads `true` either way — so it gets its own paragraph, with the
parenthetical exemption stated beside it.
- The machine kind is documented where a consumer would look for it, with the
instruction to key on the kind rather than the wording.
- The skipped-text note no longer implies it reports date shapes; it
deliberately does not, and silently omitting that left the doc promising the
behaviour this round removed.
CHANGESET (round 4 review Minor 4). CONTRIBUTING.md's format is
`**<Bold user-visible change>** — <symptom-led explanation>.` and both
canonical examples are one sentence; this fragment ran three. Now one, and
covering what the round actually delivers rather than only the range shape it
started from.
* test(#3697): keep phase.test.cjs off the docs-guard exemption fingerprint
A comment added earlier in this round named `docs/CLI-TOOLS.md` by path. The
docs-guard exemption ratchet (#3753 FIX 3) fingerprints literal `docs/`
references in exempt test files and fails when a new one appears, so that
comment turned four green gates red — `ci-docs-guard-registry` and the
registration lint — for a file that reads no documentation at all.
Caught by diffing the full suite's failing-name set against the same suite run
at `upstream/next` in a probe worktree: 33 of 37 failures reproduce at base
(install / config-home / shadowing tests under the sandbox HOME), and exactly
these 4 did not.
Rephrased rather than baselined. Adding the path to
DOCS_GUARD_EXEMPT_DOCS_PATHS is the sanctioned response when a test genuinely
starts READING a new docs path — the violation text asks the author to
re-confirm the exemption still holds. Nothing here reads documentation; the
guard matched prose. Baselining would have recorded a coupling that does not
exist and made the next reader wonder what phase.test.cjs does with
CLI-TOOLS.md. The comment still names where the contract is written, just
without planting a path string.
* fix(#3697): close four defects this round's own pre-push review drove
An adversarial cross-AI review of this round, run before the push, returned 6
CONFIRMED and 4 REFUTED. Every refutation was driven against the built tree,
and every one was a shape the author had not probed — the rules were correct
across the probe set and wrong just outside it.
(1) R4 FALSE POSITIVE, and it is the #2334 over-warning class arriving through
the rule added to close a different hole. `REQ-01, see ADR-7: section 3` fired:
`ADR-7:` is the same shave class as `REQ-01;`, and the parenthetical test does
not reach a BARE citation. The FP probe that scored this rule 0/0 only ever
tested the parenthesised form.
Fixed by requiring the dropped id's prefix to agree with a SELECTED id — the
module's own idiom, not a new heuristic: `reqEndpointsImplyInterior` already
demands an agreeing prefix for the same reason. Cost, stated in the census: a
dropped id whose prefix is on no selected id (`REQ-01, FOO-02: x`) stays
silent. Same trade the strict-dash rule takes — under-report a rare shape
rather than over-report a common one. Pinned as a declared blind spot by
(2) R4 FALSE NEGATIVE, on the DOCUMENTED form. `[REQ-01; REQ-02]` dropped
REQ-01 silently: the selector strips square brackets and R4's raw scanner did
not. The bracket spelling the shipped template recommends was the one shape the
rule could not see.
(3) The rider filter suppressed a REGISTERED requirement. `API-2-01` is a legal
requirement id — gap-checker's `parseRequirements` accepts it from
REQUIREMENTS.md — so a `\d+-\d+` filter hid a genuinely dropped requirement
behind a rule meant only to hide dates. Narrowed to a four-digit year segment.
The earlier #3697-18 case asserting `API-2-01` should be suppressed is REMOVED,
and the removal is recorded in place: its premise was refuted, it was not
inconvenient.
(4) An INVISIBLE line warned. A lone U+200B carried a token to the parser while
reading as empty to the author, so R3b fired with nothing on screen to explain
it. Zero-width and format characters are now stripped — stripped rather than
treated as delimiters, because splitting on one would fabricate two fragments
out of one ID.
Also corrects the documentation the same review found overstated: the line is
split on commas AND whitespace, and the ID shape is matched case-insensitively,
so `REQ-01 REQ-02` and `req-01, req-02` both select and neither warns. That was
pre-existing selector behaviour; this round is the one that asserted the docs
were true of it.
Tests: #3697-19 (four invisible-only shapes), -19b (embedded zero-width is
stripped, not split on), -19c (three citation forms), -19d (both bracket
spellings), -19e (both halves of the rider boundary), -19f (the declared blind
spot), -19g (the two documented tolerances). 500 tests in phase.test.cjs, 0
failures; lint:ci clean.
* fix(#3697): generalise the drop rule, and stop the invisible fix hiding a drop
The pre-push review's continuation refuted six of seven follow-up claims. The
first one is the one that mattered: the invisible-character fix committed in
c7dce173a INTRODUCED #3697's own defect. Stripping zero-width characters from
the detector wholesale made `REQ-01<ZWSP>, REQ-02` go SILENT — the selector
really does drop REQ-01, and the strip removed the only evidence of it. The
test written alongside asserted the tokens and the empty R4 result and never
asserted `warn`, so it DOCUMENTED the bug rather than catching it; that
omission was the reviewer's own MISSED finding.
An invisible is two different questions about one character, and the fix is to
stop conflating them: absence-of-content for the empty test, DECORATION on a
token for the drop rule. Neither is a reason to delete it from the line.
R4 is generalised accordingly, because the continuation drove four more shapes
a trailing-delimiter-only regex could not see — `REQ-01 ;REQ-02`,
`REQ-01 :REQ-02`, `**REQ-01;** REQ-02`, the backticked form — plus
`**REQ-01**, REQ-02`, where emphasis alone defeats the selector. These are one
class: decoration on a token the selector then cannot take. One rule, not four
patches; patching them individually is how a list stays short and wrong.
PARENTHESES ARE NOT DECORATION, and the suite caught me learning that: shaving
them made `REQ-01, (REQ-02), REQ-03 — REQ-05` report a glued delimiter that was
never there and broke #3697-9d's channel routing with it. A parenthesis is this
rule's citation marker.
The rider stops adjudicating an undecidable shape. `API-2-01` is a legal
requirement id and `API-2026-08` is too, while `FY-26-08` and `FY-2026-08-15`
are dates — no regex separates them, and both filters this round tried scored a
miss in each direction. It now NAMES the token and states the ambiguity, which
is the same thing the two warning voices already do about a range separator.
Filtering hides a real dropped requirement; reporting it bare asks the author
whether a date is a requirement; saying "this may equally be a date" does
neither.
The census and the docs are corrected to what the code does, including the part
that is NOT complete: the prefix gate does not stop a citation that SHARES a
selected prefix (`ADR-01, see ADR-7: sec 3` fires), and nothing at token level
separates that from a real drop. A prose heuristic on "see" is the free-text
detector this module exists to avoid, so the honest move is to say so.
CLAIM 17 — the invariant that actually matters — came back CONFIRMED on a
20,000-run fast-check property over arbitrary Unicode: `citedReqIds` is
identical to upstream/next's for every input, and marking is untouched.
513 tests in phase.test.cjs, 0 failures; lint:ci clean.
* fix(#3697): gate the drop rule on evidence, and stop an unmatched paren swallowing the line
Third pass of the round's own pre-push review, scoped to regression-hunting
rather than further polish. Three findings, all driven, all mine.
R4 OVER-WARNED on markdown styling. `REQ-01, see **REQ-7** for context` claimed
a dropped requirement: the previous cut treated any shaved decoration as
evidence, and emphasis is not evidence. Nothing separates that line from
`**REQ-01**, REQ-02` meaning to list one, so the rule now requires a positive
signal — a glued `;`/`:` (a list separator was INTENDED) or an invisible (the
token is CORRUPTED; nobody types one on purpose). Emphasis alone falls back to
the skipped-text rider, which names the id without asserting a drop, exactly as
`(REQ-02)` is handled. That is the #2334 class caught one cut before shipping.
R4 UNDER-WARNED on `**REQ-01**; REQ-02` — one shave pass cannot reach a wrapper
sitting behind a delimiter. Shaves to a stable point now.
The range OPERATOR lost its invisibles handling. `REQ-01 <ZWSP>..<ZWSP> REQ-05`
went silent, because the previous commit removed the invisible strip from BOTH
the tokenizer and R4 when only R4's was wrong. An invisible is two questions
about one character: for the classification rules it is noise and is stripped
from the token; for the drop rule it is the evidence and must survive on the
raw line. Stripping in both places hid a dropped id; stripping in neither hid a
range. The reviewer's MISSED finding named the missing control — regression
tests covered invisibles inside ids and not beside operators — and #3697-19i is
that control.
UNBALANCED PARENTHESES swallowed the line. `REQ-01, (note REQ-02; REQ-03`
reported nothing: a running-depth counter left the unclosed `(` open through
end-of-line, so every genuine drop after it inherited citation immunity. A
parenthesis confers that immunity only as part of a MATCHED span now — an
unmatched one is a typo, not a citation.
CLAIM 22 re-confirmed on a fresh 20,000-run property over arbitrary Unicode:
`citedReqIds` identical to upstream/next, marking untouched, warnings appended.
522 tests in phase.test.cjs, 0 failures; lint:ci rc=0; full suite carries zero
head-only failures against a probe worktree at upstream/next.
* fix(#3697): make delimiter ADJACENCY the rule, and delete matched citations outright
Fourth and final pass of the round's own pre-push review. Three findings, and
they shared one root cause, so this is a narrower rule rather than a longer list
of shapes.
TOKEN-WIDE PAREN IMMUNITY LEAKED. `REQ-01, REQ-02;(note) REQ-03` is a single
whitespace token, so a matched parenthetical inside it conferred immunity on the
`REQ-02;` sitting OUTSIDE the parens, and the drop went silent. Matched spans
are now deleted from the line outright — which states what is actually meant,
that for this rule a citation is not on the line — and an UNMATCHED paren is a
typo that confers nothing. That also retires the running-depth counter whose
previous bug was the mirror image: an unclosed `(` swallowing the rest of the
line.
DECORATION WAS TESTED TOKEN-WIDE, so `REQ-01, see **REQ-7**; next topic` was
reported as a dropped requirement. It is a citation with sentence punctuation.
The rule is now ADJACENCY: styling is stripped, then the `;`/`:` must be
touching the id. `REQ-01;`, `;REQ-02` and `**REQ-01;**` qualify;
`**REQ-01**;` does not, because outside the styling that character is
punctuation. An invisible needs no adjacency test — nobody types one on
purpose, so anywhere in the token it is corruption rather than intent.
`**REQ-01**; REQ-02` therefore goes silent, and the test row asserting
otherwise is inverted rather than deleted quietly: it was added one commit ago
on the reasoning this pass refuted, and nothing distinguishes it from
`see **REQ-7**; next topic`.
Worth recording plainly: three successive cuts of this rule fired on a
citation, and each fix was a narrower definition of EVIDENCE, never a longer
list of shapes. The list-lengthening instinct is what produced the bug each
time.
The review's last MISSED finding named the missing control — the paren tests
all surrounded matched spans with whitespace, so none covered a span sharing a
token with an id outside it. #3697-19j carries both directions now.
526 tests in phase.test.cjs, 0 failures; lint:ci rc=0; full suite zero
head-only failures against a probe at upstream/next; the invariant that
`citedReqIds` is identical to upstream re-confirmed on 20,000 arbitrary
Unicode inputs.
* fix(#3697): state R4's real boundary, and stop the over-cap voice masking a drop
Two defects, both found by this round's own pre-publication body claim-audit.
1. A DEMONSTRATED drop was discarded by the unverified voice. On
`REQ-01, REQ-02: <2049 chars>` the analyzer names REQ-02 in
delimiterDroppedIds and the formatter then reported `req-line-unverified`,
whose message never mentions it — the one actionable finding masked by the
token beside it. The over-cap channel now excludes a line carrying an R4
hit, exactly as rangeReadingOnly already did and for the same reason: that
voice's whole claim is that nothing could be checked, and R4 has already
checked something. The assertive channel still carries the over-cap rider,
so nothing about the cap is traded away. Pinned by #3697-19l, which fails
against the pre-fix build and nothing else does.
2. Three shipped artifacts asserted behaviour the code does not have — the
same class as this PR's round-4 blocker, re-committed. CONTEXT.md's rules
predicate, the CLI tools reference, and the warning's own advice string all
listed markdown emphasis as an R4 trigger. It is not: styling is shaved
BEFORE the test and tolerated around an id, never a trigger on its own, so
`**REQ-01**, REQ-02` and `**REQ-01**; REQ-02` are both silent. The trigger
is exactly a glued `;`/`:` or an embedded invisible.
The census predicate was wrong in a second way. Its 26-spelling separator
sweep found only `;` and `:` because the sweep was SYMMETRIC-ONLY and
therefore biased: one-sided attachment drops silently for every punctuation
outside the set — `/ | & + . > \` and the full-width and non-ASCII forms
`； ， ؛` all measured silent. The domain is wide open and R4 covers two
characters of it. Said plainly in all three places rather than widened
here: every previous widening of this rule first fired on a citation, so it
is not done blind at the end of a round.
Both blind spots are now PINNED as tests (#3697-19m styling-only, #3697-19n
one-sided separators) so the documents and the code cannot drift apart again —
which is what the round-4 blocker asked for.
tests/phase.test.cjs: 542 tests, 542 pass, 0 fail, 0 skip. lint:ci rc=0.
Both CONTEXT-INDEX consumers regenerated.
* fix(#3697): re-sweep the separator census properly, and say what it really found
The round-4 census in src/phase.cts concluded "exactly two — `; ` and `: `"
from a 26-spelling sweep. That conclusion was forced by how the sweep was
built, not by the code: it swept the ONE-SIDED form (`REQ-01; REQ-02`) for the
semicolon and colon, and only the BARE and SYMMETRIC forms (`|`, ` | `) for
every other separator. Different members of the domain were tested in
different shapes, so no other answer was reachable. Caught by this round's
pre-publication claim-audit of the response comment, reading the census
comment against its own swept list.
Re-swept fully crossed and driven through the built artifact: 21 separators x
{bare, trailing-space, leading-space, both-spaces} = 84 combinations. 26 select
both ids, 24 under-select and already warn, and 34 UNDER-SELECT SILENTLY. All
34 are one shape — a separator glued to exactly one of the two ids, e.g.
`REQ-01/ REQ-02` or `REQ-01 /REQ-02` — for every punctuation except `,` and
the `;`/`:` that R4 covers.
So R4 covers TWO CHARACTERS of a wide-open domain. That is now what the census
comment, the CONTEXT.md census-domains predicate and the CLI tools reference
all say. The set is deliberately not widened here: three successive cuts of
this rule fired on a citation, and a fourth at the end of a round with no
adversarial pass is how each of those got in.
Second false passage in the same block: styling-only decoration was described
as "left to the skipped-text rider, which names the id". A rider only exists
inside a message, and a message only exists once some rule sets `warn` — so on
a line where nothing else fires, `REQ-01, **REQ-02**` is wholly silent.
Describing it as handled reads as coverage. #3697-19m already pins the silence.
so the test matches the documented claim.
tests/phase.test.cjs: 552 tests, 552 pass, 0 fail, 0 skip. lint:ci rc=0.
Both CONTEXT-INDEX consumers regenerated.
* chore(#3697): regenerate both CONTEXT-INDEX.json after rebasing onto next
Rebased onto next @ f4fefb0be. The two generated indexes conflicted on the
replay and were resolved by regenerating, not by hand-merging:
`npm run gen:context-index` for docs/CONTEXT-INDEX.json and
`node examples/dynamic-context-management/gen-context-index.cjs --write` for
the example's copy. Against next, each now differs only in the eight
PHASE.REQ-LINE.SEAM.* predicates this PR adds (plus the PHASE class and the
count); every base-side change (the SEAM.* predicates, the ADR-3942 value
rewrites) is carried. `lint-example-parser-parity` and
`gen-context-index --check` both pass.
* fix(#3697): an over-cap token outranks the ambiguous range voice
Round 7 review, Minor 1. `rangeReadingOnly`'s guard conjunction checked
`hasGluedRangeFragment`, `inertIdShaped` and `delimiterDroppedIds` but not
`oversizedTokens`, so a line carrying a clean, fully-selected spaced range
*and* an unrelated token past the 2048-char scan cap was coded
`req-line-range-reading` — a code CONTEXT.md's PHASE.REQ-LINE.SEAM.kinds
predicate documents as "nothing was dropped" — over a token no rule (R1-R4
all skip over-cap tokens) had ever examined. Since the PR tells machine
consumers to branch on `.code` rather than parse prose, that is a false
"nothing to verify further" signal.
The review's suggested fix was to add `oversizedTokens.length === 0` to the
conjunction. That clause is right and is here, but on its own it routes the
line to the ASSERTIVE channel: `req-line-misparse`, whose message says the
line "could not be parsed as a comma-separated REQ-ID list" on a line where
every ID present was in fact selected. That is the #2334 over-warning class
this module's own channel-selection docblock exists to prevent — a false-clean
code traded for a false-assertion one. So the correct destination is
`req-line-unverified`: the line was not CHECKED, which is not the same as
clean, and nothing on it demonstrably failed to parse either.
Both non-assertive voices were carrying their own inline copy of the same
"nothing was demonstrably dropped" conjunction, and that duplication is what
let them drift: `rangeReadingOnly` omitted the cap, while the over-cap channel
excluded a spaced range wholesale via `!hasSpacedRange`. Extract it once as
`nothingDemonstrablyDropped` and have both read it. The new predicate is a
strict superset of the old `!hasSpacedRange` guard — `spacedRangePairs.every()`
is vacuously true when no spaced range fired — so the over-cap channel's
behaviour on every line without a spaced range is unchanged, and R2 firing on
an endpoint the selector did not take still routes to the assertive channel.
Exactly one input class changes routing: a clean fully-selected spaced range
beside an unexamined over-cap token, which moves from `req-line-range-reading`
to `req-line-unverified`. Pinned by `#3697-19n` (the twin of `#3697-19l` on
the other side of the boundary — there a demonstrated drop outranks the
unverified voice, here the cap outranks the ambiguous one), with `#3697-19o`
as the negative control asserting a clean range with nothing over the cap is
still a range reading.
* docs(#3697): state the warning-code precedence, and what the cap condition actually is
Two surfaces, one point. The round 7 finding cited CONTEXT.md's
PHASE.REQ-LINE.SEAM.kinds predicate as the documentation of what
`req-line-range-reading` claims, and it was right to: that predicate said "R2
alone fired on selected endpoints; nothing was dropped" with no mention of the
scan cap, describing a line the code could not distinguish from one carrying a
token it never examined.
The range reading is the weakest of the three claims and yields to the other
two: a demonstrated drop makes the line a misparse, and a token the cap left
unclassified makes it unverified. `docs/CLI-TOOLS.md` gains that sentence; the
CONTEXT.md predicate gains it plus two precision points that this round's own
pre-push adversarial review extracted over three passes, each with a driven
counterexample I reproduced before acting on it:
* "nothing was dropped" overstates the rule. The discriminator is RULE-scoped
by design (round 3, Major 3), so that a parenthesised ID-shaped token does
not re-open the #2334 over-warning class — `(REQ-02)` is indistinguishable
from `(ADR-7)` at token level and is carried by the skipped-text rider, never
by this code. `REQ-01, (REQ-02), REQ-03 - REQ-05` selects three, names REQ-02
as skipped, and is still a range reading. The predicate now says "no rule
named a dropped ID", which is what the code tests.
* The deferral condition is `oversizedTokens` being non-empty, NOT the presence
of a token past the cap. Those differ: a long token the selector itself took
can be exempt, because selection is uncapped and anchored and such a token
was therefore examined. `RANGE-01 - RANGE-05, R-<2047 sevens>` yields
`oversizedTokens=[]` and stays a range reading. Two earlier attempts to
characterise WHEN the exemption applies were both refuted — the neighbour
test admits any non-short neighbour, not just a range operator — so the
predicate now states the condition and defers the exemption's own rule to
SEAM.cap rather than paraphrasing it a third time.
Verified after the edit: deferral holds if and only if the cap left a token
unclassified, across all three counterexamples plus controls, and an exempt
selector-taken long token is exhibited. No behaviour change — predicate text,
one CLI-reference paragraph, and the two regenerated indexes. Predicate count
unchanged at 285 across 22 classes, 0 duplicate ids; lint-example-parser-parity
and both `--check` generators pass.
* test(#3697): rename the round 7 regression pair — 19n was already taken
Self-found immediately after the push, before anything was published to the
review thread. The two tests added this round were named `#3697-19n` and
`#3697-19o`, and `#3697-19n` was already in use: it is the declared-blind-spot
case for one-sided separators in both attachment directions, generated inside a
loop with a computed label, which is why a grep for a literal `test('#3697-19n'`
did not find it. The PR body's own *Declared blind spots* list already refers to
`#3697-19n` with that meaning.
Nothing failed. Duplicate test names do not error, and the suite stayed green at
567/567 — which is the argument for fixing it rather than against. Two concrete
costs: any TAP name-set differential collapses same-named tests under `sort -u`,
so one of the two becomes invisible to exactly the did-not-run and pass->fail
checks that name-set comparison exists to perform; and a reviewer reading
"#3697-19n" in the body now gets a different test than the one the body means.
Renamed to `#3697-19p` (over-cap beside a clean range) and `#3697-19q` (its
negative control), the next free ids in the series; the pre-existing `#3697-19n`
is untouched at its original 4 occurrences. Cross-references inside the renamed
block were updated with them. Negative control re-run under the new ids: 19p
still fails against pre-fix source and passes after, 19q passes at both ends.
---------
Co-authored-by: Tom Boucher <trekkie@nomorestars.com>
This commit is contained in:
0xdhx
5
.changeset/zesty-wasps-fly.md
Normal file
5
.changeset/zesty-wasps-fly.md
Normal file
@@ -0,0 +1,5 @@
|
||||
---
|
||||
type: Fixed
|
||||
pr: 3744
|
||||
---
|
||||
**`phase complete` now warns when the ROADMAP `**Requirements**:` line under-selects REQ-IDs** — a range (`REQ-01 … REQ-05`), a glued `;` or `:` delimiter (`REQ-01; REQ-02`), and any non-placeholder wording that selects nothing (`Deferred`, `N/A`) all marked fewer requirements than the line names while still reporting `requirements_updated: true` with zero warnings, and each now emits a warning naming what was selected and what was skipped, carrying a machine-readable kind, without expanding ranges or changing which IDs get marked. (#3697)
|
||||
@@ -721,6 +721,14 @@ The prompt-level data/instruction isolation seam for untrusted web/document ingr
|
||||
`LIVE-CONFIG.GUARD.SEAM.truncation=MAX_ENTRIES/MAX_DEPTH bound the walk; a bound hit sets truncated and diffLiveConfig emits kind:'unverified' — a truncated scan MUST NOT read as clean; boundary covered at {limit-1,limit,limit+1} via newestMtime's injected budget plus fast-check monotonicity, per RULESET.TESTS.boundary-coverage + RULESET.TESTS.property-based-testing`
|
||||
`LIVE-CONFIG.GUARD.SEAM.severity=reports by default locally; CI wires GSD_STRICT_LIVE_CONFIG_GUARD=1 on Linux/macOS lanes (test.yml, all three test jobs) so a suite-produced leak FAILS those runs; Windows lanes stay report-only pending the documented pre-existing USERPROFILE sweep (~190 test sites sandbox HOME alone) — promote once that lands; skipped by GSD_SKIP_LIVE_CONFIG_GUARD=1`
|
||||
`LIVE-CONFIG.GUARD.SEAM.ci-blind=the AMBIENT-ENV half stays CI-blind — CI never has these vars set, so green CI is not evidence for it; what strict mode catches in CI is the suite's own default-root leaks (HOME/USERPROFILE-derived), the guard remains the only loud signal for ambient-var escapes`
|
||||
`PHASE.REQ-LINE.SEAM.module=src/phase.cts owns the ROADMAP **Requirements**: line seam as TWO module-scope functions, extracted so the parser is directly testable (a closure inside cmdPhaseComplete is reachable only by spawning the CLI, which no fast-check property can do): analyzeRequirementsLine(rawLine) -> RequirementsLineAnalysis, formatRequirementsLineWarning(phaseNum,rawLine,analysis) -> {code,message}|null; both exported, plus REQ_LINE_WARNING_CODE`
|
||||
`PHASE.REQ-LINE.SEAM.selector-identity=citedReqIds is BYTE-IDENTICAL to the pre-extraction expression and is the ONLY thing that reaches the ledger; every rule below adds to warnings[] and NOTHING else — a change that alters what phase.complete MARKS is out of this seam's contract, not a refinement of it`
|
||||
`PHASE.REQ-LINE.SEAM.rules=R1 whole-token range | R2 spaced operator between two selected interior-implying endpoints | R2' operator glued to one endpoint | R3 zero selection with ID-shaped residue | R3b zero selection on any non-placeholder non-empty line (#3697 AC-1b/AC-4) | R4 an ID the selector dropped to DECORATION — the TRIGGER is exactly a glued ;/: at either end OR an embedded invisible, never styling: quotes/backticks/emphasis are TOLERATED around the id (shaved before the test) but do NOT fire on their own, so `**REQ-01**, REQ-02` and `**REQ-01**; REQ-02` are BOTH silent — plus outside any MATCHED parenthetical AND sharing a prefix with a SELECTED id (square brackets stripped as the selector strips them; parentheses deliberately NOT, they are the citation marker) | over-cap unclassified; warn is their disjunction, named rather than inlined in the return literal`
|
||||
`PHASE.REQ-LINE.SEAM.kinds=three, carried as a machine code BESIDE the prose, never instead of it — req-line-misparse (ID-shaped content demonstrably not selected) | req-line-range-reading (R2 alone fired on selected endpoints and NO RULE NAMED A DROPPED ID — rule-scoped, never line-global: an unselected parenthetical is carried by the skipped-text rider, not by this code — so the voice must NOT claim a parse failure; it defers to req-line-unverified when the cap left a token UNCLASSIFIED, which is narrower than 'a token past the cap' — a long token the SELECTOR ITSELF took can be exempt, so the condition is oversizedTokens being non-empty, never the mere presence of a long token — see SEAM.cap for the exemption's own rule) | req-line-unverified (a token past the cap: the line was not classified, which is not the same as clean); emitted as the additive result field requirements_line_warning, because warnings[] is a documented string[] rendered by execute-phase.md and re-typing its elements is a breaking output-contract change; ABSENT entirely on a clean line`
|
||||
`PHASE.REQ-LINE.SEAM.cap=REQ_TOKEN_SCAN_LIMIT=2048 bounds every predicate including each range participant's NEIGHBOURS, not just the operator; a bound hit sets oversizedTokens and takes the unverified kind — an unexaminable token MUST NOT read as clean, and the cap bounds the WORK, never the warning; boundary covered at {2047,2048,2049} across BOTH capped predicate families per RULESET.TESTS.boundary-coverage`
|
||||
`PHASE.REQ-LINE.SEAM.placeholder=TBD/NONE as the LEAD token only, and R3b's non-empty test keys on VISIBLE content (a line of only zero-width/bidi/variation-selector codepoints is empty; an invisible INSIDE a token is decoration and R4 reports the drop); that gate — not the ID-shape gate — is what holds the whole #2334/#2339 negative space silent under R3b (measured: 15 of 15 fixtures held by non-zero selection or placeholderLed, 0 by ID shape)`
|
||||
`PHASE.REQ-LINE.SEAM.census-domains=TWO open domains, each censused in-source with its NOT-reached consequence: range-operator spellings (reached: ..+, seven Unicode dashes plus ASCII -, …, to/thru/through; not reached: →, ~, ..=, ..<, until, up to) and comma-SUBSTITUTE separators (round 4's 26-spelling sweep concluded 'exactly ; and : ' because it swept the ONE-SIDED form for ;/: and only the BARE and SYMMETRIC forms for every other separator — different members tested in different shapes, so the answer was forced; re-swept round 5 FULLY CROSSED at 21 separators x {bare,trailing-space,leading-space,both} = 84, driven: 26 select both, 24 already warn, 34 UNDER-SELECT SILENTLY and all 34 are one-sided attachment — | / + & \ > . ! ? • · ؛ ； ， － ~ and/plus — so R4 covers TWO CHARACTERS of a WIDE-OPEN domain, never the whole of it); R4's own NOT-reached set is therefore styling-only decoration, every non-;/: attachment, anything inside a MATCHED parenthetical, and any decorated id whose prefix is on NO selected id (REQ-01, FOO-02: x stays silent even when FOO-02 is real); the prefix gate is NOT complete in the other direction either — a citation SHARING a selected prefix (REQ-01, see REQ-7: sec 3) still fires and nothing at token level separates it from a real drop`
|
||||
`PHASE.REQ-LINE.SEAM.gap-checker-divergence=normalizePhaseReqIds (src/gap-checker.cts) is a SECOND parser of the same ROADMAP value and DIVERGES on four axes — ranges (expanded there, never here, deliberately per #3697) | placeholder vocabulary (whole trimmed value after stripping parens there, LEAD token here) | parentheses (stripped there, not here) | ID shape (PHASE_REQ_ID_SHAPE_RE is wider) — pinned in BOTH directions by #3697-17 rather than unified, because unifying would change what phase.complete MARKS; consequence is user-visible: RANGE-01..RANGE-05 reports 5 requirements to gap analysis and 0 to phase complete`
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -283,6 +283,136 @@ consumer using `wave` for scheduling (`WAVE_FILTER`, the wave-safety check)
|
||||
is still working from the degraded assignment; only the diagnostic surfaces
|
||||
the loss.
|
||||
|
||||
### The ROADMAP `**Requirements**:` line grammar
|
||||
|
||||
`phase complete` reads each phase's `**Requirements**:` line to decide which
|
||||
REQ-IDs to mark. The grammar is deliberately small, and it is documented here
|
||||
because the command now warns about it (#3697) — a warning about a rule that
|
||||
cannot be looked up is not actionable.
|
||||
|
||||
**The canonical form is a comma-separated list of REQ-IDs.** Square brackets are
|
||||
optional; a REQ-ID is `PREFIX-N`, where the prefix is a letter followed by
|
||||
letters or digits. Two tolerances are worth knowing because the warnings below
|
||||
do **not** fire on them: the line is split on commas *and whitespace*, so
|
||||
`REQ-01 REQ-02` selects both; and the ID shape is matched case-insensitively,
|
||||
so `req-01` is selected and marked. Write the comma list anyway — it is what
|
||||
every template and every example uses — but neither spelling is an error:
|
||||
|
||||
```
|
||||
**Requirements**: REQ-01, REQ-02, REQ-03
|
||||
**Requirements**: [REQ-01, REQ-02, REQ-03]
|
||||
```
|
||||
|
||||
**Ranges are not expanded** — `REQ-01 … REQ-05` selects the two endpoints and
|
||||
nothing between them, and `REQ-01..REQ-05` selects nothing at all, because the
|
||||
whole token fails the ID shape. This is a deliberate non-feature, not an
|
||||
oversight: the line is a traceability record, and silently inventing IDs that
|
||||
appear nowhere in `REQUIREMENTS.md` is worse than declining to.
|
||||
|
||||
**A deliberately empty line is written `TBD` or `None`.** Those two words are
|
||||
the placeholder vocabulary, and they are matched as the line's leading token, so
|
||||
`None (per ADR-7)` and `**None**` are declared-empty too. **Any other wording
|
||||
that selects no REQ-IDs warns** — `Deferred`, `N/A`, `Pending`, `TBA`, a bare
|
||||
`-`, or free prose — because from the command's side an unrecognised word is
|
||||
indistinguishable from a line that was meant to cite requirements and failed
|
||||
to. A line whose only content is an HTML comment is not "other wording" and
|
||||
stays silent, so the shipped template's own `<!-- ... -->` does not warn.
|
||||
|
||||
**Write each requirement as a bare ID, separated by a comma.** The line is
|
||||
split on commas and whitespace only, and nothing else is stripped, so anything
|
||||
attached to an ID takes the ID with it. `REQ-01; REQ-02` marks **only**
|
||||
`REQ-02`; so do `REQ-01 ;REQ-02`, `**REQ-01;** REQ-02` and an ID carrying a
|
||||
stray invisible character. Those are the cases the warning names — it reports
|
||||
the dropped ID, because this is the quietest way to lose a requirement here
|
||||
(the command reports `requirements_updated: true` either way).
|
||||
|
||||
**What the warning does NOT reach.** Stated so its silence is not read as a
|
||||
clean bill, and enumerated rather than summarised, because each of these is a
|
||||
requirement that goes missing without a word. The check fires only when the
|
||||
thing touching the ID is a `;`, a `:`, or an invisible character:
|
||||
|
||||
- **Markdown styling on its own is silent.** `**REQ-01**, REQ-02` drops
|
||||
`REQ-01` and says nothing at all. Styling is not evidence that a separator
|
||||
was meant. `**REQ-01**; REQ-02` is silent for the same reason — the `**`
|
||||
sits between the ID and the `;`, so nothing is touching the ID.
|
||||
- **Any other attached punctuation is silent.** `REQ-01/ REQ-02`,
|
||||
`REQ-01| REQ-02`, `REQ-01. REQ-02`, `REQ-01+ REQ-02`, `REQ-01> REQ-02` and
|
||||
their full-width and non-ASCII equivalents (`；`, `，`, `؛`) each mark only
|
||||
`REQ-02`. A fully crossed sweep — 21 separators against bare, leading-space,
|
||||
trailing-space and both-spaces spellings, 84 combinations — found **34**
|
||||
silent under-selections, every one of them a separator glued to exactly one
|
||||
of the two IDs. Only `;` and `:` are in the set. Widening it is a live
|
||||
option — say the word — but each past widening of this check first fired on
|
||||
a citation, so it is not done blind.
|
||||
- **A dropped ID whose prefix matches nothing selected is silent.**
|
||||
`REQ-01, REQ-02: login` is reported; `REQ-01, FOO-02: x` is not. A citation
|
||||
is textually identical to a dropped requirement — `REQ-01, see ADR-7:
|
||||
section 3` carries `ADR-7:` in exactly the shape `REQ-01;` has — and prefix
|
||||
agreement is the only thing that separates them without guessing at prose.
|
||||
Anything inside matched parentheses is left alone for the same reason:
|
||||
`(see ADR-7: section 3)` is a citation.
|
||||
|
||||
The prefix gate is not complete in the other direction either: a citation that
|
||||
*shares* a selected prefix — `REQ-01, see REQ-7: sec 3` — does warn, naming
|
||||
`REQ-7` as dropped. Nothing at the token level separates that from a real
|
||||
drop.
|
||||
|
||||
**Dash spellings need a full ID on both sides.** `REQ-01-REQ-05` reads as a
|
||||
range; `REQ-01-05` does not, and neither does any of its typographic variants
|
||||
(en dash, em dash, minus sign, and the rest). The reason is that
|
||||
`PREFIX-<digits><dash><digits>` is also a date (`FY-2026-08`) and a sub-numbered
|
||||
ID (`API-2-01`), so warning on it would be noise on lines that are perfectly
|
||||
correct. `..`, `…`, `to`, `thru` and `through` have no such reading and do
|
||||
accept a bare numeric endpoint (`REQ-01..05`). The cost is that
|
||||
`REQ-01, REQ-02-05` is not reported; a bare `REQ-02-05` still is, because it
|
||||
selects nothing.
|
||||
|
||||
**What warns, and in which of the three voices.** All go to `warnings[]` and
|
||||
none blocks completion:
|
||||
|
||||
- *"could not be parsed as a comma-separated REQ-ID list"* — the line did not
|
||||
yield the requirements it appears to name. That covers two cases, and the
|
||||
message says which one it is: ID-shaped text on the line was **not**
|
||||
selected, so something was demonstrably dropped; **or** the line selected
|
||||
nothing at all while not being a `TBD`/`None` placeholder, in which case
|
||||
there may be no ID-shaped text on it whatsoever (`Deferred` takes this
|
||||
voice). Either way nothing was marked and the line needs fixing.
|
||||
- *"contains what reads as a range between two cited REQ-IDs"* — the separator
|
||||
is the only thing in question: a separator between two cited IDs could equally
|
||||
be a range or an annotation, and the command cannot tell them apart, so it
|
||||
states both readings rather than asserting a failure that may not have
|
||||
happened. It speaks about the **separator**, not about the whole line. It is
|
||||
also the *weakest* of the three claims, so it yields to the other two: a
|
||||
demonstrated drop elsewhere on the line makes it a misparse, and an
|
||||
unexamined over-cap token makes the line unverified — a voice whose claim is
|
||||
that nothing was dropped cannot speak over a token no rule read.
|
||||
|
||||
**Each warning carries a machine-readable kind.** The prose goes to
|
||||
`warnings[]` as before — that field is unchanged and is still an array of
|
||||
strings — and the kind is emitted beside it as `requirements_line_warning`,
|
||||
one of `req-line-misparse`, `req-line-range-reading` or `req-line-unverified`.
|
||||
The field is absent entirely when the line is clean. Key on the kind rather
|
||||
than on the wording; the wording is free to improve.
|
||||
|
||||
Either of those two voices may add a factual note naming **ID-shaped text on the
|
||||
line that was not selected**. Square brackets *are* stripped — `[REQ-01, REQ-02]`
|
||||
is the documented form — but parentheses are not, so `(REQ-02)` is not marked.
|
||||
The command cannot tell that from `(ADR-7)`, which is a citation and correctly
|
||||
ignored, so it names what it skipped and leaves the judgement to you. Where the
|
||||
skipped text is `PREFIX-<digits>-<digits>` — the shape the dash rule above
|
||||
declines to adjudicate, because `FY-2026-08` is a date and `API-2-01` is a
|
||||
legal requirement id and no rule separates them — it is still named, with that
|
||||
ambiguity stated alongside it. Naming it and saying why it is ambiguous beats
|
||||
both alternatives: filtering it hides a real dropped requirement, and reporting
|
||||
it bare asks you to check whether a date is a requirement.
|
||||
The third voice is for input the command could not examine: *"could not be
|
||||
checked ... the REQ-ID selection on this line is unverified"*. Range detection
|
||||
is bounded at 2,048 characters per token, so a longer token is not classified —
|
||||
and unclassified is reported, never treated as clean. Selection itself is *not*
|
||||
bounded, so a valid REQ-ID longer than that is still selected and marked
|
||||
normally; it only triggers this voice if something beside it could have formed a
|
||||
range with it, which is the case where the bound actually suppressed a check.
|
||||
|
||||
---
|
||||
|
||||
## Roadmap Commands
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"schemaVersion": 1,
|
||||
"count": 277,
|
||||
"count": 285,
|
||||
"classes": {
|
||||
"ARCH": 1,
|
||||
"CI": 2,
|
||||
@@ -10,6 +10,7 @@
|
||||
"LEARNING": 1,
|
||||
"LIVE-CONFIG": 6,
|
||||
"META": 4,
|
||||
"PHASE": 8,
|
||||
"PLANNING": 3,
|
||||
"PR": 2,
|
||||
"PRED": 68,
|
||||
@@ -190,6 +191,46 @@
|
||||
"klass": "META",
|
||||
"value": "read CONTRIBUTING.md sections \"Pull Request Guidelines\" + \"CHANGELOG Entries\" before EVERY agent dispatch"
|
||||
},
|
||||
{
|
||||
"id": "PHASE.REQ-LINE.SEAM.cap",
|
||||
"klass": "PHASE",
|
||||
"value": "REQ_TOKEN_SCAN_LIMIT=2048 bounds every predicate including each range participant's NEIGHBOURS, not just the operator; a bound hit sets oversizedTokens and takes the unverified kind — an unexaminable token MUST NOT read as clean, and the cap bounds the WORK, never the warning; boundary covered at {2047,2048,2049} across BOTH capped predicate families per RULESET.TESTS.boundary-coverage"
|
||||
},
|
||||
{
|
||||
"id": "PHASE.REQ-LINE.SEAM.census-domains",
|
||||
"klass": "PHASE",
|
||||
"value": "TWO open domains, each censused in-source with its NOT-reached consequence: range-operator spellings (reached: ..+, seven Unicode dashes plus ASCII -, …, to/thru/through; not reached: →, ~, ..=, ..<, until, up to) and comma-SUBSTITUTE separators (round 4's 26-spelling sweep concluded 'exactly ; and : ' because it swept the ONE-SIDED form for ;/: and only the BARE and SYMMETRIC forms for every other separator — different members tested in different shapes, so the answer was forced; re-swept round 5 FULLY CROSSED at 21 separators x {bare,trailing-space,leading-space,both} = 84, driven: 26 select both, 24 already warn, 34 UNDER-SELECT SILENTLY and all 34 are one-sided attachment — | / + & \\ > . ! ? • · ؛ ； ， － ~ and/plus — so R4 covers TWO CHARACTERS of a WIDE-OPEN domain, never the whole of it); R4's own NOT-reached set is therefore styling-only decoration, every non-;/: attachment, anything inside a MATCHED parenthetical, and any decorated id whose prefix is on NO selected id (REQ-01, FOO-02: x stays silent even when FOO-02 is real); the prefix gate is NOT complete in the other direction either — a citation SHARING a selected prefix (REQ-01, see REQ-7: sec 3) still fires and nothing at token level separates it from a real drop"
|
||||
},
|
||||
{
|
||||
"id": "PHASE.REQ-LINE.SEAM.gap-checker-divergence",
|
||||
"klass": "PHASE",
|
||||
"value": "normalizePhaseReqIds (src/gap-checker.cts) is a SECOND parser of the same ROADMAP value and DIVERGES on four axes — ranges (expanded there, never here, deliberately per #3697) | placeholder vocabulary (whole trimmed value after stripping parens there, LEAD token here) | parentheses (stripped there, not here) | ID shape (PHASE_REQ_ID_SHAPE_RE is wider) — pinned in BOTH directions by #3697-17 rather than unified, because unifying would change what phase.complete MARKS; consequence is user-visible: RANGE-01..RANGE-05 reports 5 requirements to gap analysis and 0 to phase complete"
|
||||
},
|
||||
{
|
||||
"id": "PHASE.REQ-LINE.SEAM.kinds",
|
||||
"klass": "PHASE",
|
||||
"value": "three, carried as a machine code BESIDE the prose, never instead of it — req-line-misparse (ID-shaped content demonstrably not selected) | req-line-range-reading (R2 alone fired on selected endpoints and NO RULE NAMED A DROPPED ID — rule-scoped, never line-global: an unselected parenthetical is carried by the skipped-text rider, not by this code — so the voice must NOT claim a parse failure; it defers to req-line-unverified when the cap left a token UNCLASSIFIED, which is narrower than 'a token past the cap' — a long token the SELECTOR ITSELF took can be exempt, so the condition is oversizedTokens being non-empty, never the mere presence of a long token — see SEAM.cap for the exemption's own rule) | req-line-unverified (a token past the cap: the line was not classified, which is not the same as clean); emitted as the additive result field requirements_line_warning, because warnings[] is a documented string[] rendered by execute-phase.md and re-typing its elements is a breaking output-contract change; ABSENT entirely on a clean line"
|
||||
},
|
||||
{
|
||||
"id": "PHASE.REQ-LINE.SEAM.module",
|
||||
"klass": "PHASE",
|
||||
"value": "src/phase.cts owns the ROADMAP **Requirements**: line seam as TWO module-scope functions, extracted so the parser is directly testable (a closure inside cmdPhaseComplete is reachable only by spawning the CLI, which no fast-check property can do): analyzeRequirementsLine(rawLine) -> RequirementsLineAnalysis, formatRequirementsLineWarning(phaseNum,rawLine,analysis) -> {code,message}|null; both exported, plus REQ_LINE_WARNING_CODE"
|
||||
},
|
||||
{
|
||||
"id": "PHASE.REQ-LINE.SEAM.placeholder",
|
||||
"klass": "PHASE",
|
||||
"value": "TBD/NONE as the LEAD token only, and R3b's non-empty test keys on VISIBLE content (a line of only zero-width/bidi/variation-selector codepoints is empty; an invisible INSIDE a token is decoration and R4 reports the drop); that gate — not the ID-shape gate — is what holds the whole #2334/#2339 negative space silent under R3b (measured: 15 of 15 fixtures held by non-zero selection or placeholderLed, 0 by ID shape)"
|
||||
},
|
||||
{
|
||||
"id": "PHASE.REQ-LINE.SEAM.rules",
|
||||
"klass": "PHASE",
|
||||
"value": "R1 whole-token range | R2 spaced operator between two selected interior-implying endpoints | R2' operator glued to one endpoint | R3 zero selection with ID-shaped residue | R3b zero selection on any non-placeholder non-empty line (#3697 AC-1b/AC-4) | R4 an ID the selector dropped to DECORATION — the TRIGGER is exactly a glued ;/: at either end OR an embedded invisible, never styling: quotes/backticks/emphasis are TOLERATED around the id (shaved before the test) but do NOT fire on their own, so `**REQ-01**, REQ-02` and `**REQ-01**; REQ-02` are BOTH silent — plus outside any MATCHED parenthetical AND sharing a prefix with a SELECTED id (square brackets stripped as the selector strips them; parentheses deliberately NOT, they are the citation marker) | over-cap unclassified; warn is their disjunction, named rather than inlined in the return literal"
|
||||
},
|
||||
{
|
||||
"id": "PHASE.REQ-LINE.SEAM.selector-identity",
|
||||
"klass": "PHASE",
|
||||
"value": "citedReqIds is BYTE-IDENTICAL to the pre-extraction expression and is the ONLY thing that reaches the ledger; every rule below adds to warnings[] and NOTHING else — a change that alters what phase.complete MARKS is out of this seam's contract, not a refinement of it"
|
||||
},
|
||||
{
|
||||
"id": "PLANNING.PATH.PARITY.project-scope",
|
||||
"klass": "PLANNING",
|
||||
|
||||
File diff suppressed because one or more lines are too long
844
src/phase.cts
844
src/phase.cts
@@ -2425,6 +2425,797 @@ function phaseDisplayNameFromSlug(slug: string | null): string | null {
|
||||
return name || null;
|
||||
}
|
||||
|
||||
// ─── #3697: the `**Requirements**:` line under-selection detector ────────────
|
||||
//
|
||||
// EXTRACTED from cmdPhaseComplete (round 3, review finding Blocker 1). The
|
||||
// detection logic below is a parser, so `RULESET.TESTS.property-based-testing`
|
||||
// requires at least one fast-check property test over it — and that is not
|
||||
// reachable while the logic is a closure inside a command that only a
|
||||
// subprocess can invoke (every #3697 test spawns the CLI; 100 fc runs cannot).
|
||||
// Extraction is therefore load-bearing, not tidying: it is what makes the
|
||||
// property test and the 2048-boundary fixtures (Blocker 2) expressible at all.
|
||||
//
|
||||
// BEHAVIOUR IS UNCHANGED BY THE MOVE. The two tokenizations below stay
|
||||
// deliberately DIFFERENT and are co-located so they cannot drift apart:
|
||||
// * the SELECTOR strips `[` and `]` only, then splits on `[,\s]+`. Its output
|
||||
// IS `citedReqIds` — the ledger-writing set — so widening it would change
|
||||
// what phase-complete marks, which #3697 explicitly does not do.
|
||||
// * the DETECTOR additionally shaves brackets/quotes/emphasis and trailing
|
||||
// sentence punctuation, so it can see an operator or an ID that the
|
||||
// selector's stricter shape filter rejects.
|
||||
// The gap between them is not a defect: it is why `ADR-7)` is not selected
|
||||
// while `ADR-7` is still nameable in a warning.
|
||||
//
|
||||
// The `**Requirements**: TBD` placeholder is what phase.add / -batch / -insert
|
||||
// seed (three sites in this file — locate them by the literal
|
||||
// `Requirements**: TBD`, never by line number: an earlier revision of this
|
||||
// comment cited 833/920/1078, which had drifted to 1132/1237/1413 by round 3).
|
||||
// The shipped comma-list template is `gsd-core/templates/roadmap.md:32`.
|
||||
type RequirementsLineAnalysis = {
|
||||
/** The ledger-writing set — byte-identical to the pre-extraction selector. */
|
||||
citedReqIds: string[];
|
||||
/** The detector's shaved tokens (see the tokenization note above). */
|
||||
tokens: string[];
|
||||
/** R1 — tokens that are THEMSELVES a range (`RANGE-01..RANGE-05`). */
|
||||
rangeTokens: string[];
|
||||
/** R2 — a bare operator with a selected, interior-implying ID either side. */
|
||||
hasSpacedRange: boolean;
|
||||
/** R2' — an operator GLUED to one endpoint (`RANGE-01 -RANGE-05`). */
|
||||
hasGluedRangeFragment: boolean;
|
||||
/** R3 — zero selection on a non-placeholder line, with ID-shaped residue. */
|
||||
inertIdShaped: string[];
|
||||
/**
|
||||
* R3b — zero selection on a non-placeholder line that carries ANY content.
|
||||
*
|
||||
* This is #3697's AC-1b/AC-4 verbatim ("warn when `citedReqIds.length === 0`
|
||||
* while the raw capture is non-empty and not `TBD`"), and it is deliberately
|
||||
* NOT gated on ID-shaped residue the way R3 is. Round 4 measured the reason:
|
||||
* every one of the fifteen #2334/#2339 negative-space fixtures is held
|
||||
* silent by non-zero SELECTION or by `placeholderLed`, and not one of them by
|
||||
* the ID-shape gate — so the gate was buying no negative space while costing
|
||||
* the acceptance criterion. `Deferred`, `N/A`, `Pending`, `TBA` and `-` were
|
||||
* silent because of it, while the docs, this census and the advice string all
|
||||
* said they warned.
|
||||
*/
|
||||
zeroSelectionInert: boolean;
|
||||
/**
|
||||
* R4 — REQ-IDs the SELECTOR dropped because a delimiter was glued to them.
|
||||
*
|
||||
* `REQ-01; REQ-02` selects only `REQ-02`: the selector splits on `[,\s]+`,
|
||||
* so `REQ-01;` keeps its semicolon and fails the anchored ID shape. This is
|
||||
* #3697's own half-success failure mode — `requirements_updated: true` with
|
||||
* a silently unmarked requirement — reached by one wrong delimiter.
|
||||
*
|
||||
* Round 4 review called this indistinguishable from a parenthesised
|
||||
* citation, because `(ADR-7)` also shaves to a bare ID. At the RAW token
|
||||
* level they are not: `REQ-01;` is shaved of a trailing DELIMITER,
|
||||
* `ADR-7)` of a citation wrapper. This rule keys on that shave class and
|
||||
* requires the token to sit outside any parenthetical, which is what keeps
|
||||
* `(see ADR-7: section 3)` silent.
|
||||
*/
|
||||
delimiterDroppedIds: string[];
|
||||
/** Tokens past the scan cap that could carry an ID — reported, never dropped. */
|
||||
oversizedTokens: string[];
|
||||
/** ID-shaped tokens the selector did not take. Reported as a fact; never routes. */
|
||||
unselectedIdShaped: string[];
|
||||
/** The line leads with `TBD` / `None`. */
|
||||
placeholderLed: boolean;
|
||||
/** R2's hits, as `[left, right]` endpoint pairs, so the channel below can ask
|
||||
* about the endpoints the rule actually fired on. */
|
||||
spacedRangePairs: Array<[string, string]>;
|
||||
/**
|
||||
* Nothing on the line was DEMONSTRABLY dropped: no rule that names a specific
|
||||
* unselected ID fired, and any spaced range fired on endpoints the selector
|
||||
* actually took.
|
||||
*
|
||||
* This is the shared precondition of both NON-assertive voices — the
|
||||
* ambiguous range reading and the over-cap "not classified" report — and it
|
||||
* is named once because they had drifted apart. Round 7 review, Minor 1:
|
||||
* `rangeReadingOnly` carried the conjunction inline and omitted the cap,
|
||||
* while the over-cap channel carried its own copy that excluded a spaced
|
||||
* range wholesale. A line with a clean, fully-selected range beside an
|
||||
* unexamined over-cap token satisfied neither guard as intended and reached
|
||||
* the ambiguous voice.
|
||||
*/
|
||||
nothingDemonstrablyDropped: boolean;
|
||||
/**
|
||||
* The round-3 channel discriminator (review finding Major 3). True when the
|
||||
* ONLY thing to report is a range *reading*: R2 fired, no other rule did, and
|
||||
* every endpoint R2 fired on was actually selected. Nothing was dropped, so
|
||||
* the line did not fail to parse and the warning must not claim it did.
|
||||
*
|
||||
* This is deliberately RULE-SCOPED rather than line-global. A line-global
|
||||
* "was anything ID-shaped left unselected?" test reads correctly on the
|
||||
* motivating example and misroutes as soon as the line carries an unrelated
|
||||
* parenthesised citation: `RANGE-01, RANGE-02 — RANGE-05 deferred per
|
||||
* (ADR-7)` has `(ADR-7)` outside the selector's bracket strip, so a global
|
||||
* test calls it a drop and sends the line back to the assertive channel —
|
||||
* reinstating exactly the false "could not be parsed" claim Major 3 is
|
||||
* about, and contradicting #3697-4, which pins a parenthetical citation as
|
||||
* NOT unparsed residue. Only the rules that fired may speak.
|
||||
*/
|
||||
rangeReadingOnly: boolean;
|
||||
/** Any rule fired — the line warrants a warning. */
|
||||
warn: boolean;
|
||||
};
|
||||
|
||||
// A range operator, enumerated. CENSUS (round 3): the domain is "separator
|
||||
// spellings an author can put between two REQ-IDs", which is open, so the
|
||||
// enumeration draws a boundary rather than covering it. Reached: ASCII `..`+,
|
||||
// the seven Unicode dashes that are the SAME operator at different codepoints
|
||||
// (U+2010 hyphen, U+2011 non-breaking hyphen, U+2012 figure dash, U+2013 en,
|
||||
// U+2014 em, U+2015 horizontal bar, U+2212 minus) plus ASCII `-`, U+2026
|
||||
// ellipsis, and the words `to`/`thru`/`through`. NOT reached, and the
|
||||
// consequence is a silent under-selection — #3697's own defect — for that
|
||||
// spelling: `→`, `~`, `..=`, `..<`, `until`, and `up to` (two tokens, so it
|
||||
// cannot be one operator token at all). Those stay out deliberately: each is a
|
||||
// symbol or word with an independent non-range use between two IDs, which is
|
||||
// the over-warning class #2334 cost three rounds. The Unicode dashes DO carry
|
||||
// the ASCII hyphen's date/sub-number collision — an earlier round-3 commit
|
||||
// claimed they did not, and was wrong — so they take the strict arm with it;
|
||||
// see the rule below.
|
||||
const REQ_RANGE_DASHES = '\\u2010\\u2011\\u2012\\u2013\\u2014\\u2015\\u2212';
|
||||
// EVERY DASH IS STRICT — one rule, whatever the codepoint. `PREFIX-\d+ <dash>
|
||||
// \d+` is also a date (`FY-2026-08`) and a sub-numbered ID (`API-2-01`), and
|
||||
// that ambiguity is a property of the SHAPE, not of which dash key was pressed.
|
||||
// The design already chose strictness for ASCII `-` on exactly this trade: a
|
||||
// bare-hyphen tight range must carry a full ID on BOTH sides. Until round 3 the
|
||||
// other dashes sat in the loose arm, so `RANGE-01 (target FY-2026<en-dash>08)`
|
||||
// warned while its all-ASCII twin — pinned silent by #3697-4 — did not. That
|
||||
// inconsistency predates this PR for U+2013/U+2014; round 3 briefly widened it
|
||||
// to five more codepoints before this commit closed it for all seven.
|
||||
// The cost is symmetric and already accepted: `RANGE-01, RANGE-02<dash>05`
|
||||
// goes silent, exactly as `RANGE-01, RANGE-02-05` already does today. A bare
|
||||
// `RANGE-02<dash>05` still warns — it selects nothing, so R3 catches it.
|
||||
// LOOSE stays loose: `..`, `…` and the word operators have no date or
|
||||
// sub-number reading between two numbers, so they keep the numeric endpoint.
|
||||
const REQ_RANGE_OP = `(?:\\.{2,}|\\u2026|[${REQ_RANGE_DASHES}]|-|to|thru|through)`;
|
||||
const REQ_RANGE_OP_LOOSE = `(?:\\.{2,}|\\u2026|to|thru|through)`;
|
||||
const REQ_RANGE_OP_SYMBOL = `(?:\\.{2,}|\\u2026|[${REQ_RANGE_DASHES}]|-)`;
|
||||
const REQ_RANGE_TOKEN_RE = new RegExp(
|
||||
`^([A-Z][A-Z0-9]*)-(?:\\d+)\\s*(?:${REQ_RANGE_OP_LOOSE}\\s*(?:\\1-)?|[-${REQ_RANGE_DASHES}]\\s*\\1-)\\d+$`,
|
||||
'i',
|
||||
);
|
||||
const REQ_PURE_RANGE_OP_RE = new RegExp(`^${REQ_RANGE_OP}$`, 'i');
|
||||
const REQ_GLUED_RANGE_LEAD_RE = new RegExp(`^${REQ_RANGE_OP_SYMBOL}([A-Z][A-Z0-9]*-\\d+)$`, 'i');
|
||||
const REQ_GLUED_RANGE_TRAIL_RE = new RegExp(`^([A-Z][A-Z0-9]*-\\d+)${REQ_RANGE_OP}$`, 'i');
|
||||
const REQ_ID_SUBSTRING_RE = /[A-Z][A-Z0-9]*-\d+/i;
|
||||
const REQ_ID_SHAPE_RE = /^[A-Z][A-Z0-9]*-\d+$/i;
|
||||
const REQ_ID_PARTS_RE = /^([A-Z][A-Z0-9]*)-(\d+)$/i;
|
||||
// `LETTERS-\d+-\d+` — a date (`FY-2026-08`) or a sub-numbered ID (`API-2-01`).
|
||||
// REQ_RANGE_TOKEN_RE's strict-dash arm exists precisely to keep this shape
|
||||
// silent, because nothing at token level can tell the three readings apart.
|
||||
// Round 4 review Minor 2: the skipped-text rider re-reported it through the
|
||||
// side door — `REQ_ID_SUBSTRING_RE` is unanchored, so `FY-2026-08` matches as
|
||||
// `FY-2026` and landed in `unselectedIdShaped`. Whenever any OTHER rule fired
|
||||
// on a line carrying a date annotation, the warning then told the author to
|
||||
// "check whether any of it is a requirement" about a date. Not a false
|
||||
// warning — the line was warning anyway — but false CONTENT, and it is the
|
||||
// #2334 voice.
|
||||
// `PREFIX-<digits>-<digits>` — the shape the strict-dash range rule refuses to
|
||||
// act on because it is equally a date (`FY-2026-08`) and a sub-numbered id
|
||||
// (`API-2-01`). NO regex separates those: `API-2026-08` is a legal requirement
|
||||
// id and `FY-26-08` is a date, and both filters that tried scored a miss in
|
||||
// each direction under the pre-push review's continuation.
|
||||
//
|
||||
// So the rider stops adjudicating and starts DISCLOSING. Round 4 Minor 2's
|
||||
// real complaint was that the rider told the author to check whether a DATE
|
||||
// was a requirement; the fix is to name the ambiguity rather than to guess at
|
||||
// it — which is the same thing the two warning voices already do about a
|
||||
// range separator.
|
||||
const REQ_AMBIGUOUS_NUMERIC_RE = /^[A-Z][A-Z0-9]*(?:-\d+){2,}$/i;
|
||||
|
||||
// The token-length cap. It bounds REQ_ID_SUBSTRING_RE, the one UNANCHORED
|
||||
// regex here, which backtracks quadratically on a pathological token. Round 3
|
||||
// review Nit 6 objected that the anchored regexes were left uncapped on the
|
||||
// strength of a comment asserting they scan linearly; they are applied through
|
||||
// the same cap now, so the claim is enforced rather than asserted. No real
|
||||
// REQ-ID-carrying token approaches this bound.
|
||||
const REQ_TOKEN_SCAN_LIMIT = 2048;
|
||||
|
||||
/**
|
||||
* The Requirements-line warning KINDS, as a stable machine vocabulary (round 4
|
||||
* review Major 3).
|
||||
*
|
||||
* Before this, the kind existed only in the prose of the message, so every
|
||||
* consumer and every test had to regex an English sentence — and rewording a
|
||||
* message silently un-asserted the tests that pinned it. The repo already had
|
||||
* the settled seam for exactly these semantics: `diffLiveConfig` emits
|
||||
* `kind:'unverified'` for a truncated scan (`CONTEXT.md`), and
|
||||
* `WAVE_CLEANUP_WARNING` carries codes in `src/worktree-safety.cts`.
|
||||
*
|
||||
* Carried ALONGSIDE the prose, never instead of it. `warnings[]` is a
|
||||
* documented `string[]` in `phase complete`'s JSON output, rendered by
|
||||
* execute-phase.md's "If has_warnings is true" step, so changing its element
|
||||
* shape would be a breaking output-contract change for a shipped command. The
|
||||
* code is emitted as its own additive `requirements_line_warning` field.
|
||||
*/
|
||||
const REQ_LINE_WARNING_CODE = {
|
||||
/** ID-shaped content was demonstrably not selected — the line failed to parse. */
|
||||
misparse: 'req-line-misparse',
|
||||
/** A range READING is at stake; every endpoint the rule fired on was selected. */
|
||||
rangeReading: 'req-line-range-reading',
|
||||
/** A token past the scan cap means the line was not classified — never that it is clean. */
|
||||
unverified: 'req-line-unverified',
|
||||
} as const;
|
||||
|
||||
type ReqLineWarningCode = (typeof REQ_LINE_WARNING_CODE)[keyof typeof REQ_LINE_WARNING_CODE];
|
||||
|
||||
/** The formatter's result. `null` still means CLEAN, which is a value, not a failure. */
|
||||
type ReqLineWarning = { code: ReqLineWarningCode; message: string };
|
||||
|
||||
// R4 — a full ID with a trailing statement delimiter glued to it. ANCHORED on
|
||||
// both ends, so it is linear and needs no cap of its own beyond the token
|
||||
// length guard its caller applies.
|
||||
// Zero-width, bidi-control, joiner and variation-selector codepoints. INVISIBLE
|
||||
// to the author, and the pre-push review's continuation drove the consequence
|
||||
// from both sides: a line of only these warned with nothing on screen to
|
||||
// explain it, AND stripping them wholesale from the detector made
|
||||
// `REQ-01<ZWSP>, REQ-02` go SILENT while the selector really did drop REQ-01 —
|
||||
// #3697's own defect, introduced by the fix for its mirror image. So they are
|
||||
// never stripped from the line: they are DECORATION on a token (R4 below) and
|
||||
// absence-of-content for the empty test (visibleContent), which are two
|
||||
// different questions about the same character.
|
||||
const REQ_INVISIBLE_RE = /[\u00AD\u200B-\u200F\u2060-\u2064\u2066-\u2069\uFE0F\uFEFF]/g;
|
||||
// The wrappers R4 shaves. Emphasis, quotes and backticks, because the SELECTOR
|
||||
// shaves none of them — `**REQ-01**` is genuinely not selected and is a real,
|
||||
// silent drop.
|
||||
//
|
||||
// PARENTHESES ARE DELIBERATELY ABSENT, and this is load-bearing. A parenthesis
|
||||
// is this rule's citation MARKER, not decoration to shave: `(REQ-02)` and
|
||||
// `(ADR-7)` are the same shape and the rule declines both. Including them here
|
||||
// made `REQ-01, (REQ-02), REQ-03 — REQ-05` report a glued delimiter that was
|
||||
// never there, and broke #3697-9d's channel routing with it — caught by the
|
||||
// suite immediately after the widening.
|
||||
const REQ_WRAPPER_RE = /^["'`*_~“”‘’]+|["'`*_~“”‘’]+$/g;
|
||||
// An id with a list delimiter glued to EITHER end, once styling is removed.
|
||||
// The capture is the bare id; a match means the delimiter was ADJACENT to it.
|
||||
const REQ_DELIMITED_ID_RE = /^[;:]*([A-Z][A-Z0-9]*-\d+)[;:]*$/i;
|
||||
|
||||
|
||||
|
||||
/**
|
||||
* CENSUS (round 4): the domain is "separators an author writes between two
|
||||
* REQ-IDs INSTEAD of a comma" — distinct from the range-operator domain
|
||||
* censused above, and it had no census at all before this round.
|
||||
*
|
||||
* ROUND 4'S CENSUS WAS WRONG, AND THE WAY IT WAS WRONG IS THE LESSON. It swept
|
||||
* 26 spellings and concluded "exactly two — `; ` and `: `". It reached that
|
||||
* answer because it swept the ONE-SIDED form (`REQ-01; REQ-02`) for the
|
||||
* semicolon and colon, and only the BARE and SYMMETRIC forms (`|`, ` | `) for
|
||||
* every other separator. Different members of the domain were tested in
|
||||
* different shapes, so the conclusion could not have come out any other way.
|
||||
*
|
||||
* Re-swept round 5, fully crossed: 21 separators x {bare, trailing-space,
|
||||
* leading-space, both-spaces} = 84 combinations, driven through the built
|
||||
* artifact. 26 select both IDs, 24 under-select and already warn, and
|
||||
* 34 UNDER-SELECT SILENTLY. All 34 are the same shape — a separator glued to
|
||||
* exactly ONE of the two IDs, e.g. `REQ-01/ REQ-02` or `REQ-01 /REQ-02` — for
|
||||
* every punctuation except `,` (the real delimiter) and `;` / `:` (R4).
|
||||
* Measured silent: | / + & \ > . ! ? • · ؛ ； ， － ~ and the word operators
|
||||
* `and` / `plus` in trailing-space form.
|
||||
*
|
||||
* So the honest statement is that R4 covers TWO CHARACTERS of a domain that is
|
||||
* wide open, not that the domain has two members. The round-4 review
|
||||
* hand-listed the semicolon; the colon is its sibling and fails identically;
|
||||
* everything else in that list is disclosed here and NOT caught. Widening the
|
||||
* delimiter class is a small change and deliberately not made at the end of a
|
||||
* round: three successive cuts of this rule fired on a citation.
|
||||
*
|
||||
* THE GATE IS ADJACENCY, and it is the part to read. Styling is stripped, then
|
||||
* the delimiter must be touching the id: `REQ-01;`, `;REQ-02`, `**REQ-01;**`
|
||||
* and the backticked form all qualify. `**REQ-01**;` does NOT — outside the
|
||||
* styling a `;` is sentence punctuation, which is why `REQ-01, see **REQ-7**;
|
||||
* next topic` is a citation and not a drop. An INVISIBLE anywhere in the token
|
||||
* qualifies without an adjacency test, because nobody types one on purpose, so
|
||||
* it is corruption rather than intent.
|
||||
*
|
||||
* Markdown styling on its own is NOT a trigger and NOT reported. It reaches
|
||||
* the skipped-text rider, which names the id without asserting a drop — but a
|
||||
* rider only exists inside a MESSAGE, and a message only exists when some rule
|
||||
* set `warn`. On a line where nothing else fires, `REQ-01, **REQ-02**` is
|
||||
* wholly silent. Saying it is "left to the rider" reads as coverage and is
|
||||
* not; #3697-19m pins the silence so this comment cannot drift back.
|
||||
*
|
||||
* NOT reached, stated rather than fixed, and the second member is WIDER than
|
||||
* this comment first claimed:
|
||||
* - anything inside a parenthetical. A parenthesis is this rule's citation
|
||||
* MARKER, never decoration to shave — `(REQ-02)` and `(ADR-7)` are the
|
||||
* same shape and the rule declines both.
|
||||
* - a decorated id whose prefix is on NO selected id: `REQ-01, FOO-02: x`
|
||||
* stays silent even when FOO-02 is real. Prefix agreement is what
|
||||
* separates a drop from a bare citation — `REQ-01, see ADR-7: section 3`
|
||||
* carries `ADR-7:` in exactly `REQ-01;`'s shape — and it is the module's
|
||||
* own idiom, not a new heuristic (reqEndpointsImplyInterior already
|
||||
* requires an agreeing prefix). The gate is NOT complete: a citation that
|
||||
* DOES share a selected prefix (`ADR-01, see ADR-7: sec 3`) still fires,
|
||||
* and nothing at token level separates that from a real drop. Saying so is
|
||||
* the honest position; a prose heuristic on "see" is exactly the free-text
|
||||
* detector this module exists to avoid.
|
||||
* The trade, plainly: an under-report on a rare shape over an over-report on a
|
||||
* common one — the same call the strict-dash rule makes.
|
||||
*/
|
||||
function reqDelimiterDroppedIds(rawLine: string, selected: Set<string>, cap: number): string[] {
|
||||
// MATCHED parenthetical spans are removed OUTRIGHT, not tracked as a depth.
|
||||
//
|
||||
// Two bugs died here. A running depth counter let an unbalanced `(` stay open
|
||||
// to end-of-line and swallow every real drop after it. Promoting a whole
|
||||
// token to immune because it CONTAINED a matched character then leaked the
|
||||
// other way: `REQ-01, REQ-02;(note) REQ-03` is one whitespace token, so the
|
||||
// parenthetical conferred immunity on the `REQ-02;` sitting outside it.
|
||||
// Deleting the span states what is actually meant — for this rule a citation
|
||||
// is not on the line — while an UNMATCHED paren is a typo and confers
|
||||
// nothing.
|
||||
//
|
||||
// Square brackets go too, exactly as the SELECTOR strips them: `[REQ-01;
|
||||
// REQ-02]` is the documented form and was silently dropping REQ-01.
|
||||
//
|
||||
// INVISIBLES STAY. They are the evidence this rule reads; the tokenizer
|
||||
// strips them for the classification rules, and the two sites answer two
|
||||
// different questions about the same character.
|
||||
const chars = [...String(rawLine).replace(/<!--[\s\S]*?-->/g, ' ')];
|
||||
const openStack: number[] = [];
|
||||
for (let i = 0; i < chars.length; i += 1) {
|
||||
if (chars[i] === '(') openStack.push(i);
|
||||
else if (chars[i] === ')' && openStack.length > 0) {
|
||||
const open = openStack.pop() as number;
|
||||
for (let j = open; j <= i; j += 1) chars[j] = ' ';
|
||||
}
|
||||
}
|
||||
const line = chars.join('').replace(/[[\]]/g, '');
|
||||
|
||||
// The prefixes actually SELECTED on this line. A dropped id must agree with
|
||||
// one of them — that is what separates a delimiter typo from a citation,
|
||||
// since `REQ-01, see ADR-7: sec 3` carries `ADR-7:` in exactly `REQ-01;`'s
|
||||
// shape. Same-prefix agreement is the module's own idiom, not a new
|
||||
// heuristic (see reqEndpointsImplyInterior).
|
||||
const selectedPrefixes = new Set<string>();
|
||||
for (const id of selected) {
|
||||
const m = REQ_ID_PARTS_RE.exec(id);
|
||||
if (m) selectedPrefixes.add(m[1].toUpperCase());
|
||||
}
|
||||
|
||||
const hits: string[] = [];
|
||||
for (const raw of line.split(/[,\s]+/)) {
|
||||
if (!raw || raw.length > cap) continue;
|
||||
// Strip STYLING only. What survives is the id plus whatever was glued
|
||||
// directly to it.
|
||||
const core = raw.replace(REQ_INVISIBLE_RE, '').replace(REQ_WRAPPER_RE, '');
|
||||
const m = REQ_DELIMITED_ID_RE.exec(core);
|
||||
if (!m) continue;
|
||||
const bare = m[1];
|
||||
// ADJACENCY IS THE WHOLE RULE. A `;`/`:` touching the id is a list
|
||||
// separator someone meant; the same character OUTSIDE the styling is
|
||||
// sentence punctuation — `see **REQ-7**; next topic` cites a requirement
|
||||
// while `**REQ-01;** REQ-02` fails to list one, and only the delimiter's
|
||||
// POSITION separates them. An INVISIBLE needs no adjacency test: nobody
|
||||
// types one on purpose, so anywhere in the token it is corruption rather
|
||||
// than intent.
|
||||
const hadAdjacentDelimiter = core !== bare;
|
||||
REQ_INVISIBLE_RE.lastIndex = 0;
|
||||
const hadInvisible = REQ_INVISIBLE_RE.test(raw);
|
||||
REQ_INVISIBLE_RE.lastIndex = 0;
|
||||
if (!hadAdjacentDelimiter && !hadInvisible) continue;
|
||||
if (selected.has(bare.toUpperCase())) continue;
|
||||
const parts = REQ_ID_PARTS_RE.exec(bare);
|
||||
if (parts && selectedPrefixes.has(parts[1].toUpperCase())) hits.push(bare);
|
||||
}
|
||||
return [...new Set(hits)];
|
||||
}
|
||||
|
||||
/** Endpoints imply a dropped interior only on an AGREEING prefix and a gap > 1. */
|
||||
function reqEndpointsImplyInterior(a: string, b: string): boolean {
|
||||
const ma = REQ_ID_PARTS_RE.exec(a);
|
||||
const mb = REQ_ID_PARTS_RE.exec(b);
|
||||
if (!ma || !mb) return false;
|
||||
if (ma[1].toUpperCase() !== mb[1].toUpperCase()) return false;
|
||||
// BigInt keeps the gap exact for numbers past 2^53.
|
||||
const gap = BigInt(mb[2]) - BigInt(ma[2]);
|
||||
return gap > 1n || gap < -1n;
|
||||
}
|
||||
|
||||
function analyzeRequirementsLine(rawLine: string): RequirementsLineAnalysis {
|
||||
const line = typeof rawLine === 'string' ? rawLine : '';
|
||||
// SELECTOR — byte-identical to the pre-extraction expression.
|
||||
const citedReqIds = line
|
||||
.replace(/[\[\]]/g, '')
|
||||
.split(/[,\s]+/)
|
||||
.map((r) => r.trim())
|
||||
.filter(Boolean)
|
||||
.filter((r) => REQ_ID_SHAPE_RE.test(r));
|
||||
|
||||
// DETECTOR tokenization. A token with NO alphanumerics is shaved of brackets
|
||||
// ONLY, so `(..)` surfaces its operator while a bare `..` is not shaved to
|
||||
// nothing by the punctuation classes. A trailing run of 2+ dots is a glued
|
||||
// range operator (`REQ-01.. REQ-05`), not sentence punctuation — keep it.
|
||||
const tokens = line
|
||||
.replace(/<!--[\s\S]*?-->/g, ' ')
|
||||
// Invisibles are removed HERE, for the classification rules — an operator
|
||||
// spelled `<ZWSP>..<ZWSP>` is still the range operator, and a line of only
|
||||
// invisibles yields no tokens at all. R4 works on the RAW line and does
|
||||
// NOT strip them, because there they are the evidence of a dropped id.
|
||||
// Removing them in both places is what made `REQ-01<ZWSP>, REQ-02` silent;
|
||||
// removing them in neither is what made `REQ-01 <ZWSP>..<ZWSP> REQ-05`
|
||||
// silent. The two questions have two different answers.
|
||||
.replace(REQ_INVISIBLE_RE, '')
|
||||
.split(/[,\s]+/)
|
||||
.map((t) => {
|
||||
const trimmed = t.trim();
|
||||
if (!/[A-Za-z0-9]/.test(trimmed)) {
|
||||
return trimmed.replace(/^[[({]+/, '').replace(/[\])}]+$/, '');
|
||||
}
|
||||
if (/\.{2,}$/.test(trimmed)) {
|
||||
return trimmed.replace(/^[[({"'`*_~“”‘’]+/, '');
|
||||
}
|
||||
return trimmed.replace(/^[[({"'`*_~“”‘’]+/, '').replace(/[\])}.;:"'`*_~“”‘’]+$/, '');
|
||||
})
|
||||
.filter(Boolean);
|
||||
|
||||
// Every predicate below is applied through the scan limit (Nit 6): a token
|
||||
// past the bound is not classified at all rather than classified expensively.
|
||||
const short = (t: string): boolean => t.length <= REQ_TOKEN_SCAN_LIMIT;
|
||||
const rangeTokens = tokens.filter((t) => short(t) && REQ_RANGE_TOKEN_RE.test(t));
|
||||
const spacedRangePairs: Array<[string, string]> = [];
|
||||
tokens.forEach((t, i) => {
|
||||
const left = tokens[i - 1] ?? '';
|
||||
const right = tokens[i + 1] ?? '';
|
||||
if (
|
||||
// EVERY participant is capped, not just the operator. Capping the operator
|
||||
// alone left `<2049-char ID> .. <2049-char ID>` running REQ_ID_SHAPE_RE and
|
||||
// BigInt over both neighbours unbounded — the cap read as uniform and was
|
||||
// not (found by the round's pre-push review).
|
||||
short(t) &&
|
||||
short(left) &&
|
||||
short(right) &&
|
||||
REQ_PURE_RANGE_OP_RE.test(t) &&
|
||||
i > 0 &&
|
||||
i < tokens.length - 1 &&
|
||||
REQ_ID_SHAPE_RE.test(left) &&
|
||||
REQ_ID_SHAPE_RE.test(right) &&
|
||||
reqEndpointsImplyInterior(left, right)
|
||||
) {
|
||||
spacedRangePairs.push([left, right]);
|
||||
}
|
||||
});
|
||||
const hasSpacedRange = spacedRangePairs.length > 0;
|
||||
// A half-spaced range splits at the tokenizer, so R1's own `\s*` never sees
|
||||
// it. SYMBOL operators only on the LEAD arm: a word operator glued to an ID
|
||||
// is an ID — `TORANGE-05` is a valid prefix-agnostic REQ-ID. The TRAIL arm
|
||||
// keeps the word operators, because a valid ID must end in digits, so
|
||||
// `REQ-01through` can only be a glued typo.
|
||||
const hasGluedRangeFragment = tokens.some((t, i) => {
|
||||
// Neighbours capped for the same reason as R2 above.
|
||||
if (!short(t)) return false;
|
||||
const before = tokens[i - 1] ?? '';
|
||||
const after = tokens[i + 1] ?? '';
|
||||
const lead = REQ_GLUED_RANGE_LEAD_RE.exec(t);
|
||||
if (
|
||||
lead &&
|
||||
i > 0 &&
|
||||
short(before) &&
|
||||
REQ_ID_SHAPE_RE.test(before) &&
|
||||
reqEndpointsImplyInterior(before, lead[1])
|
||||
) {
|
||||
return true;
|
||||
}
|
||||
const trail = REQ_GLUED_RANGE_TRAIL_RE.exec(t);
|
||||
return Boolean(
|
||||
trail &&
|
||||
i < tokens.length - 1 &&
|
||||
short(after) &&
|
||||
REQ_ID_SHAPE_RE.test(after) &&
|
||||
reqEndpointsImplyInterior(trail[1], after),
|
||||
);
|
||||
});
|
||||
const leadToken = (tokens[0] ?? '').toUpperCase();
|
||||
// CENSUS (round 3, review finding Minor 4): the placeholder domain is what
|
||||
// GSD itself seeds plus what an author writes for "deliberately empty".
|
||||
// Reached: `TBD` — the ONLY machine-written seed, at the three phase.add /
|
||||
// -batch / -insert sites — and `None`, the author convention. NOT reached:
|
||||
// `N/A`, `Deferred`, `Pending`, `TBA`, `-`. Consequence, and it is now
|
||||
// ENFORCED rather than asserted: such a line selects zero IDs and warns
|
||||
// through R3b below, which is what #3697's acceptance criterion asks for
|
||||
// ("when it selects zero IDs from a line that is non-empty and is not the
|
||||
// `TBD` placeholder"). Round 3 shipped this same paragraph while R3's
|
||||
// ID-shape gate made it false for all five words — bare `Deferred` was
|
||||
// silent, `Deferred (see ADR-7)` warned — and the claim sat in three
|
||||
// artifacts with no test in either direction. Inferring placeholder-ness
|
||||
// from arbitrary prose is still the free-text heuristic this detector
|
||||
// avoids: R3b keys on the SELECTION being empty, never on what the prose
|
||||
// means.
|
||||
const placeholderLed = leadToken === 'TBD' || leadToken === 'NONE';
|
||||
const inertIdShaped =
|
||||
citedReqIds.length === 0 && !placeholderLed
|
||||
? tokens.filter((t) => short(t) && t.includes('-') && REQ_ID_SUBSTRING_RE.test(t))
|
||||
: [];
|
||||
// R3b — the acceptance criterion's own narrow form. `tokens.length > 0` is
|
||||
// what keeps an empty line and a comment-only line silent: the tokenizer
|
||||
// strips `<!-- ... -->` before splitting, so `<!-- fill in -->` yields no
|
||||
// tokens and cannot reach this rule. Every other zero-selection,
|
||||
// non-placeholder line warns.
|
||||
const zeroSelectionInert = citedReqIds.length === 0 && !placeholderLed && tokens.length > 0;
|
||||
|
||||
// R2 is the ONLY ambiguous rule — a tight range, a glued fragment and R3
|
||||
// residue each implicate ID-shaped text the selector demonstrably did not
|
||||
// take, so any of them means the line really did fail to parse. R2 is
|
||||
// ambiguous only when its OWN endpoints were selected: the detector shaves
|
||||
// brackets and the selector does not, so R2 can fire on a `(RANGE-02)` that
|
||||
// was never selected — a real drop, and the assertive channel is right there.
|
||||
// A token past the cap is NOT classified — and must therefore not be
|
||||
// silently discarded. Round 3's first cut of the uniform cap did exactly
|
||||
// that: a 2049-char range token warned before the round and went silent
|
||||
// after it, which is #3697's own defect introduced by the fix for a nit
|
||||
// (found by the round's pre-push review). The cap bounds the WORK, not the
|
||||
// warning — so an over-cap token that could carry an ID is reported as
|
||||
// unclassified. The test is `includes('-')`, a linear scan, never the
|
||||
// unanchored regex the cap exists to keep off these tokens.
|
||||
// ANY over-cap token, not just one carrying `-`. The first cut filtered on
|
||||
// `includes('-')` and therefore missed an over-cap OPERATOR:
|
||||
// `REQ-01 <2049 dots> REQ-05` warned before this round (R2 was uncapped) and
|
||||
// went silent after it. A token we could not examine makes the line
|
||||
// unverified whatever characters it happens to contain. Computed below,
|
||||
// where the selected set is available.
|
||||
|
||||
// ID-shaped tokens the selector did not take, ANYWHERE on the line. This is
|
||||
// reported as a fact, never used to pick the channel: `(ADR-7)` and
|
||||
// `(REQ-02)` are indistinguishable by shape, so routing on it would put the
|
||||
// false "could not be parsed" claim back on a line carrying a citation.
|
||||
// Naming them lets the author see what the tokenizer skipped without the
|
||||
// warning asserting a verdict it cannot support in either direction.
|
||||
const selected = new Set(citedReqIds.map((id) => id.toUpperCase()));
|
||||
// A token the SELECTOR took has had its own SELECTION verified — the selector
|
||||
// is uncapped and anchored, so it examined the whole token. That is not the
|
||||
// same as "no rule was suppressed by it", and conflating the two was the
|
||||
// second continuation review's CLAIM J/K: two over-cap valid IDs either side
|
||||
// of `..` are both selected, both exempted, and R2 is capped — so a line that
|
||||
// warned before this round went silent, which is the very regression the
|
||||
// field exists to close, arriving through the fix for its own over-report.
|
||||
//
|
||||
// The exemption therefore applies only when nothing could have been
|
||||
// suppressed: an over-cap token that was selected AND has no neighbour that
|
||||
// could pair with it into a range. Everything else is unexaminable and is
|
||||
// reported as such.
|
||||
const couldPairIntoRange = (i: number): boolean => {
|
||||
for (const n of [tokens[i - 1], tokens[i + 1]]) {
|
||||
if (n === undefined) continue;
|
||||
if (!short(n)) return true;
|
||||
if (REQ_PURE_RANGE_OP_RE.test(n)) return true;
|
||||
if (REQ_GLUED_RANGE_LEAD_RE.test(n) || REQ_GLUED_RANGE_TRAIL_RE.test(n)) return true;
|
||||
}
|
||||
return false;
|
||||
};
|
||||
const oversizedTokens = tokens.filter(
|
||||
(t, i) => !short(t) && (!selected.has(t.toUpperCase()) || couldPairIntoRange(i)),
|
||||
);
|
||||
const unselectedIdShaped = tokens.filter(
|
||||
(t) => short(t) && REQ_ID_SUBSTRING_RE.test(t) && !selected.has(t.toUpperCase()),
|
||||
);
|
||||
// R4 runs on the RAW line, not on `tokens`: the shave that makes `REQ-01;`
|
||||
// look like a clean `REQ-01` is exactly the evidence this rule needs, so it
|
||||
// has to see the character the tokenizer removed.
|
||||
const delimiterDroppedIds = reqDelimiterDroppedIds(rawLine, selected, REQ_TOKEN_SCAN_LIMIT);
|
||||
const nothingDemonstrablyDropped =
|
||||
rangeTokens.length === 0 &&
|
||||
!hasGluedRangeFragment &&
|
||||
inertIdShaped.length === 0 &&
|
||||
// R4 is a DEMONSTRATED drop, so neither non-assertive voice — one claiming
|
||||
// nothing was dropped, the other that nothing could be checked — may speak
|
||||
// for a line carrying one.
|
||||
delimiterDroppedIds.length === 0 &&
|
||||
// R2 firing on an endpoint the selector did NOT take is itself a
|
||||
// demonstrated drop, and the assertive channel is right there. Vacuously
|
||||
// true when no spaced range fired, which is what makes this a strict
|
||||
// superset of the `!hasSpacedRange` guard the over-cap channel used to
|
||||
// carry — that channel's behaviour on a line with no spaced range is
|
||||
// unchanged, byte for byte.
|
||||
spacedRangePairs.every(([a, b]) => selected.has(a.toUpperCase()) && selected.has(b.toUpperCase()));
|
||||
const rangeReadingOnly =
|
||||
hasSpacedRange &&
|
||||
nothingDemonstrablyDropped &&
|
||||
// The cap bounds the WORK, never the warning. An over-cap token is not
|
||||
// classified by ANY rule (R1-R4 all skip it), so the voice whose entire
|
||||
// claim is that nothing was dropped has no basis to speak for this line.
|
||||
// It falls to the over-cap channel below instead — `unverified`, because
|
||||
// the line was not CHECKED; not `misparse`, because nothing on it
|
||||
// demonstrably failed to parse either. Round 7 review, Minor 1.
|
||||
oversizedTokens.length === 0;
|
||||
|
||||
// Named rather than inlined into the return literal (round 3 review Minor 3):
|
||||
// this disjunction is the module's single most important predicate, and in
|
||||
// the literal a later edit that reordered a local below the `return` would be
|
||||
// a TDZ ReferenceError at runtime rather than an error at the reader's eye
|
||||
// level. R3b joins it here — see its field docs above for why it is not
|
||||
// gated on ID shape.
|
||||
const warn =
|
||||
rangeTokens.length > 0 ||
|
||||
hasSpacedRange ||
|
||||
hasGluedRangeFragment ||
|
||||
inertIdShaped.length > 0 ||
|
||||
zeroSelectionInert ||
|
||||
delimiterDroppedIds.length > 0 ||
|
||||
oversizedTokens.length > 0;
|
||||
|
||||
return {
|
||||
citedReqIds,
|
||||
tokens,
|
||||
rangeTokens,
|
||||
hasSpacedRange,
|
||||
hasGluedRangeFragment,
|
||||
inertIdShaped,
|
||||
zeroSelectionInert,
|
||||
placeholderLed,
|
||||
spacedRangePairs,
|
||||
nothingDemonstrablyDropped,
|
||||
rangeReadingOnly,
|
||||
delimiterDroppedIds,
|
||||
oversizedTokens,
|
||||
unselectedIdShaped,
|
||||
warn,
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Render the warning, or null when the line is clean.
|
||||
*
|
||||
* TWO CHANNELS, and the split is round 3's fix for review finding Major 3. The
|
||||
* detector cannot distinguish `RANGE-02 — RANGE-05` meaning a range from the
|
||||
* same text meaning an annotation separator; they are textually identical and
|
||||
* no token-level rule separates them. What the old single-channel message did
|
||||
* was resolve that ambiguity by ASSERTION — it told the author the line "could
|
||||
* not be parsed" and to rewrite it, on a line where every ID present had in
|
||||
* fact been selected and nothing had been dropped. That is a false statement
|
||||
* under the annotation reading and the #2334 over-warning class.
|
||||
*
|
||||
* Going silent instead is not available: the range reading is equally live, and
|
||||
* staying quiet on it re-opens the exact silent under-selection #3697 is about.
|
||||
* So the ambiguity is DISCLOSED rather than decided —
|
||||
*
|
||||
* * any rule other than R2 fired, or R2 fired on an endpoint that was not
|
||||
* selected → something ID-shaped was demonstrably NOT taken. The line did
|
||||
* fail to parse; say so plainly, as before.
|
||||
* * R2 alone fired and both its endpoints were selected → nothing was
|
||||
* dropped. State both readings and let the author pick; never claim a parse
|
||||
* failure that did not occur.
|
||||
*/
|
||||
function formatRequirementsLineWarning(
|
||||
phaseNum: string,
|
||||
rawLine: string,
|
||||
analysis: RequirementsLineAnalysis,
|
||||
): ReqLineWarning | null {
|
||||
if (!analysis.warn) return null;
|
||||
const shown = String(rawLine).trim();
|
||||
const rangeRuleFired =
|
||||
analysis.rangeTokens.length > 0 || analysis.hasSpacedRange || analysis.hasGluedRangeFragment;
|
||||
|
||||
// Tokens the selector skipped, stated as a fact in EITHER channel. `(ADR-7)`
|
||||
// and `(REQ-02)` are the same shape, so no rule can say which one matters —
|
||||
// but the author can, and only if the warning tells them. Round 3's first
|
||||
// cut instead let this drive the channel, which put the false "could not be
|
||||
// parsed" claim back on a line carrying a citation.
|
||||
// Names only what the rule-specific clauses did NOT already name, so the
|
||||
// assertive voice can carry it too without repeating itself.
|
||||
const alreadyNamed = new Set(
|
||||
[...analysis.rangeTokens, ...analysis.inertIdShaped, ...analysis.delimiterDroppedIds].map((t) =>
|
||||
t.toUpperCase(),
|
||||
),
|
||||
);
|
||||
const skippedNames = analysis.unselectedIdShaped.filter((t) => !alreadyNamed.has(t.toUpperCase()));
|
||||
// Named, then qualified. The `PREFIX-N-N` shape is the one the range rules
|
||||
// deliberately decline to act on, so the rider says WHY it might not be a
|
||||
// requirement instead of silently deciding it is not.
|
||||
const ambiguousNamed = skippedNames.filter((t) => REQ_AMBIGUOUS_NUMERIC_RE.test(t));
|
||||
const skipped =
|
||||
skippedNames.length > 0
|
||||
? ` ID-shaped text on the line that was NOT selected: ${skippedNames.join(', ')}` +
|
||||
` (parentheses are not stripped, unlike square brackets) — check whether any of it is a` +
|
||||
` requirement.` +
|
||||
(ambiguousNamed.length > 0
|
||||
? ` ${ambiguousNamed.join(', ')} may equally be a date or a sub-numbered id, which is` +
|
||||
` why the range rules do not act on that shape.`
|
||||
: '')
|
||||
: '';
|
||||
// R4's clause. Named separately from the generic skipped-text rider because
|
||||
// this one is not a "check whether any of it is a requirement" hedge — the
|
||||
// token IS an ID, the selector demonstrably did not take it, and the cause
|
||||
// is nameable.
|
||||
const delimiterDropped =
|
||||
analysis.delimiterDroppedIds.length > 0
|
||||
? ` ${analysis.delimiterDroppedIds.join(', ')} ${analysis.delimiterDroppedIds.length === 1 ? 'was' : 'were'}` +
|
||||
` NOT selected: a \`;\` or \`:\` is glued to the ID, or it carries an invisible character, and` +
|
||||
` the line is split on commas and whitespace only. Write each requirement as a bare ID` +
|
||||
` separated by a comma.`
|
||||
: '';
|
||||
const oversized =
|
||||
analysis.oversizedTokens.length > 0
|
||||
? ` One or more tokens exceed the ${REQ_TOKEN_SCAN_LIMIT}-character scan limit and were NOT` +
|
||||
` classified, so this line may carry more than is reported here.`
|
||||
: '';
|
||||
|
||||
if (analysis.rangeReadingOnly) {
|
||||
// AMBIGUOUS channel — the RANGE reading is what is at stake, not a parse
|
||||
// failure: every endpoint the range rule fired on was selected.
|
||||
//
|
||||
// What this voice must NOT do is claim the whole LINE is correct. It has
|
||||
// no basis for that: an unrelated `(REQ-02)` elsewhere on the line is
|
||||
// dropped by the selector and invisible to every rule, so "nothing needs
|
||||
// to change" is an affirmative false statement on exactly the input the
|
||||
// rule-scoped discriminator was built to reach. It speaks about the
|
||||
// SEPARATOR, and defers the rest to the skipped-text clause above.
|
||||
return {
|
||||
code: REQ_LINE_WARNING_CODE.rangeReading,
|
||||
message:
|
||||
`ROADMAP Phase ${phaseNum} **Requirements** line (\`${shown}\`) contains what reads as a range ` +
|
||||
`between two cited REQ-IDs. Range forms are not expanded, so no interior IDs were selected; ` +
|
||||
`the line selected: ${analysis.citedReqIds.join(', ')}. If a range was intended, rewrite it ` +
|
||||
`naming every requirement explicitly (e.g. \`REQ-01, REQ-02, REQ-03\`); if that separator is ` +
|
||||
`an annotation rather than a range, it selected nothing to expand and needs no change.` +
|
||||
delimiterDropped +
|
||||
skipped +
|
||||
oversized,
|
||||
};
|
||||
}
|
||||
|
||||
if (analysis.oversizedTokens.length > 0 && analysis.nothingDemonstrablyDropped) {
|
||||
// A DEMONSTRATED drop outranks this voice, whose whole claim is that
|
||||
// NOTHING could be checked — both cannot be true at once. `REQ-01,
|
||||
// REQ-02: <over-cap token>` names REQ-02 in `delimiterDroppedIds` and
|
||||
// then reported `req-line-unverified`, whose message never mentions it:
|
||||
// the concrete, actionable finding masked by the token beside it. That
|
||||
// exclusion now lives in `nothingDemonstrablyDropped`, shared verbatim
|
||||
// with `rangeReadingOnly` above rather than duplicated here — the
|
||||
// duplication is what let the two drift (round 7 review, Minor 1). The
|
||||
// assertive channel already appends the over-cap rider, so routing a
|
||||
// demonstrated drop there loses nothing about the cap.
|
||||
// OVER-CAP channel — no rule could run, so no rule may be diagnosed. Say
|
||||
// exactly that: the line was not classified, rather than not a problem.
|
||||
return {
|
||||
code: REQ_LINE_WARNING_CODE.unverified,
|
||||
message:
|
||||
`ROADMAP Phase ${phaseNum} **Requirements** line (\`${shown.slice(0, 200)}…\`) could not be ` +
|
||||
`checked: one or more tokens exceed the ${REQ_TOKEN_SCAN_LIMIT}-character scan limit, so the ` +
|
||||
`REQ-ID selection on this line is unverified. Rewrite it as a comma-separated list ` +
|
||||
`(e.g. \`REQ-01, REQ-02, REQ-03\`).`,
|
||||
};
|
||||
}
|
||||
|
||||
// ASSERTIVE channel — ID-shaped content was demonstrably not selected.
|
||||
// Deliberately says "selected", NOT "marked complete": a range whose
|
||||
// endpoints are themselves unregistered selects them and marks nothing, and a
|
||||
// warning that overclaims the write is a warning the reader learns to
|
||||
// distrust.
|
||||
const selectedDesc =
|
||||
analysis.citedReqIds.length > 0
|
||||
? `the only REQ-ID(s) selected from it were: ${analysis.citedReqIds.join(', ')}`
|
||||
: 'it selected NO REQ-IDs at all, so nothing was marked';
|
||||
const unparsed = [...new Set([...analysis.rangeTokens, ...analysis.inertIdShaped])];
|
||||
// Only diagnose "range" when a range rule actually fired — an R3 warning on
|
||||
// non-range ID text must not claim one was written. And on the R3 path the
|
||||
// residue is ID-SHAPED TEXT, which is not the same claim as "a requirement we
|
||||
// failed to parse" (round 3 review finding Minor 4: `Deferred (see ADR-7)`
|
||||
// reported `ADR-7` as missed requirement content when it is a citation). Name
|
||||
// what it is, and name the placeholder escape the author actually has.
|
||||
const advice = rangeRuleFired
|
||||
? ' Range forms are not expanded; rewrite the line naming every requirement explicitly ' +
|
||||
'(e.g. `REQ-01, REQ-02, REQ-03`).'
|
||||
: ' If these are requirements, name them explicitly (e.g. `REQ-01, REQ-02, REQ-03`); if the line ' +
|
||||
'is deliberately empty, write `TBD` or `None` — any other wording selects nothing and warns.';
|
||||
return {
|
||||
code: REQ_LINE_WARNING_CODE.misparse,
|
||||
message:
|
||||
`ROADMAP Phase ${phaseNum} **Requirements** line could not be parsed as a comma-separated REQ-ID list ` +
|
||||
`(\`${shown}\`) - ${selectedDesc}.` +
|
||||
(unparsed.length > 0
|
||||
? rangeRuleFired
|
||||
? ` Unparsed text: ${unparsed.join(', ')}.`
|
||||
: ` ID-shaped text that was not selected: ${unparsed.join(', ')}.`
|
||||
: '') +
|
||||
advice +
|
||||
delimiterDropped +
|
||||
skipped +
|
||||
oversized,
|
||||
};
|
||||
}
|
||||
|
||||
function cmdPhaseComplete(cwd: string, phaseNum: string, raw: boolean): void {
|
||||
if (!phaseNum) {
|
||||
error('phase number required for phase complete');
|
||||
@@ -2493,6 +3284,11 @@ function cmdPhaseComplete(cwd: string, phaseNum: string, raw: boolean): void {
|
||||
let stateUpdated = false;
|
||||
|
||||
const warnings: string[] = [];
|
||||
// The machine kind of the Requirements-line warning, carried out to the JSON
|
||||
// result as its own field (round 4 review Major 3). Declared HERE, in the
|
||||
// same scope as `warnings[]`, because the assignment happens inside
|
||||
// withPlanningLock and the emission happens after it.
|
||||
let reqLineWarningCode: ReqLineWarningCode | undefined;
|
||||
// ADR-3408 §8.5 / D2 (#3374): "liberal but visible" — when the write-seam
|
||||
// composition's preservation stage restores a curated frontmatter value
|
||||
// over a disagreeing derived one, that divergence is surfaced here rather
|
||||
@@ -2957,27 +3753,26 @@ function cmdPhaseComplete(cwd: string, phaseNum: string, raw: boolean): void {
|
||||
const traceabilityWriteMisses: string[] = [];
|
||||
|
||||
if (reqMatch) {
|
||||
// #2334 HIGH 3: filter the tokenized capture to the REQ-ID SHAPE —
|
||||
// the SAME shape bodyReqIds (`\*\*([A-Z][A-Z0-9]*-\d+)\*\*`, below)
|
||||
// and tableReqIds (`([A-Z][A-Z0-9]*-\d+)`, below) already require —
|
||||
// so the ghost-ID / unregistered comparisons stay shape-symmetric.
|
||||
// Without this, `[^\n]+` split on `[,\s]+` turned EVERY word after
|
||||
// the ID list into a "cited REQ-ID": the shipped
|
||||
// `templates/roadmap.md:32` line
|
||||
// `**Requirements**: [REQ-01, REQ-02] <!-- brackets optional, ... -->`
|
||||
// warned to register `<!--`, `brackets`, `optional`, `-->`, etc., and
|
||||
// `**Requirements:** None` warned to register the literal word
|
||||
// `None`. This subsumes the `TBD` placeholder special-case (`TBD`
|
||||
// does not match the REQ-ID shape either); `isPlaceholderReqId` is
|
||||
// kept below as a defensive no-op for any caller that still hands
|
||||
// it a raw token.
|
||||
const REQ_ID_SHAPE_RE = /^[A-Z][A-Z0-9]*-\d+$/i;
|
||||
citedReqIds = reqMatch[1]
|
||||
.replace(/[\[\]]/g, '')
|
||||
.split(/[,\s]+/)
|
||||
.map((r) => r.trim())
|
||||
.filter(Boolean)
|
||||
.filter((r) => REQ_ID_SHAPE_RE.test(r));
|
||||
// #2334 HIGH 3 + #3697: selection and under-selection detection both
|
||||
// live in `analyzeRequirementsLine` (module scope, above), extracted in
|
||||
// round 3 so the parser is directly testable — a closure in here is
|
||||
// reachable only by spawning the CLI, which no fast-check property test
|
||||
// can do. `citedReqIds` is byte-identical to the expression that stood
|
||||
// here; nothing about what phase-complete MARKS has changed.
|
||||
const reqLineAnalysis = analyzeRequirementsLine(reqMatch[1]);
|
||||
citedReqIds = reqLineAnalysis.citedReqIds;
|
||||
const reqLineWarning = formatRequirementsLineWarning(
|
||||
phaseNum,
|
||||
reqMatch[1],
|
||||
reqLineAnalysis,
|
||||
);
|
||||
if (reqLineWarning) {
|
||||
warnings.push(reqLineWarning.message);
|
||||
// Carried out to the JSON result as its own field — see
|
||||
// REQ_LINE_WARNING_CODE for why it is not folded into
|
||||
// `warnings[]`.
|
||||
reqLineWarningCode = reqLineWarning.code;
|
||||
}
|
||||
|
||||
for (const reqId of citedReqIds) {
|
||||
const reqEscaped = escapeRegex(reqId);
|
||||
@@ -3644,6 +4439,10 @@ function cmdPhaseComplete(cwd: string, phaseNum: string, raw: boolean): void {
|
||||
auto_pruned: autoPruned,
|
||||
warnings,
|
||||
has_warnings: warnings.length > 0,
|
||||
// ADDITIVE, never a change to `warnings[]`'s element shape — that array is
|
||||
// a documented string[] consumed by execute-phase.md, so re-typing it
|
||||
// would break a shipped output contract. Absent when the line is clean.
|
||||
...(reqLineWarningCode ? { requirements_line_warning: { code: reqLineWarningCode } } : {}),
|
||||
verification_stale_check_indeterminate: staleCheckIndeterminate,
|
||||
milestone_conflict: milestoneConflict,
|
||||
preservation_warnings: preservationWarnings,
|
||||
@@ -3724,6 +4523,9 @@ export = {
|
||||
cmdPhaseInsert,
|
||||
cmdPhaseRemove,
|
||||
cmdPhaseComplete,
|
||||
analyzeRequirementsLine,
|
||||
formatRequirementsLineWarning,
|
||||
REQ_LINE_WARNING_CODE,
|
||||
cmdPhaseUatPassed,
|
||||
cmdPhaseListPlans,
|
||||
computeDependencyLevels,
|
||||
|
||||
1834
tests/phase.test.cjs
1834
tests/phase.test.cjs
File diff suppressed because it is too large
Load Diff
Reference in New Issue
Block a user