refactor(#3180): ADR-3180 behavior contract + cross-surface drift guardrails (#3223)

* refactor(#3180): one owner for completion ratio, a prompt-layer drift guard, and a written behavior contract

The 2026-08-08 coverage audit on #3180 found the epic's copy counts were a
lower bound for the third consecutive time, and that two derivation families
had never been named at all.

ADR-3180 gains Decision 7 — a normative behavior contract that says what the
right answer IS for each derivation, not merely who owns it. A reviewer with
no written rule can only ask "does this look like the others", which is how a
fifth copy passes review. Decision 4 gains (d) scan surface is every authored
surface and an owner FILE is never exempt, only its named functions; and (e)
a surface that cannot be consolidated today ships ratcheted, never unguarded.

Completion ratio: `clampPercent` sat exported and unused beside six hand-inlined
copies of its own body across five modules. All six now route through it;
`clampPercentFromFraction` is added for the one caller that already held a
fraction. Every migration is behaviour-identical — clampPercent's first line IS
the `total > 0 ? … : 0` ternary each copy carried. Guarded by
lint-completion-ratio-drift.cjs, which reports zero re-derivations with no
file-level exemption.

Prompt layer: workflow markdown re-derives live-plan counting in raw shell
(#1762), invisible to every `src/`-scoped guard. lint-planning-prompt-drift.cjs
scans it with a shrink-only baseline of the 7 sites that exist today — new
sites fail, and a baseline entry that stops firing fails too, so an
acknowledgment can never outlive the thing it describes.

lint-milestone-window-drift.cjs stops exempting its owner file wholesale; only
the four named canonical functions are exempt now. The blanket exemption was
pointed at the one file most likely to grow the next copy, and it had.

Refs #3180

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* docs(#3180): link Phases 6-8 sub-issues (#3216, #3217, #3218) from ADR-3180

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* fix(#3180): address orthogonal review — consumer-output identity tests, count-keyed ratchet, property coverage

Five findings from the two orthogonal review passes, all fixed.

Decision 4(c) breach: the completion-ratio identity test asserted at the
OWNER, which is exactly the bypass that decision exists to close — a consumer
can call clampPercent and then post-process locally, leaving both the lint and
an owner-level test green. It now drives `roadmap analyze`, `query progress`
and `stats` and asserts on their own output, over a fixture containing a
`status: superseded` plan so a consumer that re-counted raw files would report
60 where the owner reports 75.

Decision 4(e) breach: ratchet entries named the epic (#3180) rather than the
issue that removes them. They name Phase 8 (#3218) now.

The ratchet keyed on (file, text) alone, so plan-phase.md's two byte-identical
sites were one indistinguishable key and migrating either would have left the
guard green with the other alive. Entries carry an occurrence count; fewer than
acknowledged fails as a partial migration, more fails as a new copy.

Adds the missing MAX_REGEX_LITERAL_LEN boundary coverage the sibling guard's
test already had, and the fast-check property tests CONTRIBUTING requires for
clamp/budget-limit functions.

Refs #3180

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* test: stop wrapping a nested double-spawn in a 15s wall-clock budget (bug #641 probes)

`tests/ci-test-scope.test.cjs`'s `bug #641` block spawned `run-tests.cjs`
under PROBE_TIMEOUT_MS=15000; that child then spawned a nested `node --test`.
A fixed wall-clock budget around a double spawn, running inside a container
that is concurrently executing the full ~31k-test suite, fails by construction
under load.

Confirmed against three full matrix runs. Every failure was shaped
`null !== 0` — the child was KILLED, never an assertion about the thing under
test. One captured probe had already printed the correct resolution
(`suite="all" files=2: a.test.cjs b.test.cjs`) and was killed anyway. It
reproduces on `next` alone: 5 failures on linux-node22, 0 on linux-node24. The
victim subset varies by run and by lane.

What these tests are actually about is suite-token RESOLUTION — `unit` as a
bare token in --files/--files-from. Executing the seeded trivial files is
incidental and is the entire timeout surface, so the assertions move
in-process against the same functions `main()` calls, in the same order.
`parseArgs`, `selectExplicitFiles`, `selectFiles` and `walkTestFiles` are
exported for that; no behavior, signature or logic changed.

No coverage lost: `tests/run-tests-harness.test.cjs` already spawns the
harness for real and asserts exit codes end to end, on a 120s budget.

Pre-existing on `next`, fixed here rather than deferred.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* test: delete the three elapsed-time assertions

CLAUDE.md forbids asserting on wall-clock time. Three assertions did, and all
three are load-sensitive: on a saturated bench each can fail while the code
under test is correct. In every case the load-bearing assertion sits on the
line above and the timing line adds no discrimination.

run-with-timeout: the stated worry — "was this 124 the cap firing or the 30s
harness backstop?" — is already answered by the assertion above it. A backstop
kills by signal, which surfaces as status null, never 124. Observed directly
this session: three matrix runs produced exactly that null shape from killed
children.

normalize-test-command and context-predicates: both bounded a ReDoS check.
A threshold only ever separates "fast" from "slightly slow", which is bench
load, not correctness — catastrophic backtracking on 800 KB of input does not
take 251ms, it does not finish at all. A real regression therefore shows up as
the suite being killed on that test, which is louder and more reliable than a
number. The structural assertions (returned unchanged; cleanly rejected) are
what actually carry those tests, and they stay.

The sweep now reports zero elapsed-time assertions in tests/. The remaining
Date.now() uses are unique-path suffixes, barrier deadlines, fixture
timestamps and fake mtimes — none of them assertions.

Pre-existing on `next`, fixed here rather than deferred.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* chore(#3180): backfill changeset PR number (#3223)

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* fix(#3180): key the prompt-drift ratchet on POSIX paths so it works on Windows

The baseline keys on (file, trimmed text). `file` came from scanTree's
`path.relative()`, which uses NATIVE separators, while the committed baseline
stores POSIX. On Windows every violation was therefore unmatched — reported as
FRESH — and every baseline entry matched nothing — reported as STALE. The guard
failed 100% of the time there, on both CI shards:

  ✖ scanRepo(repoRoot) matches the baseline exactly: zero fresh AND zero stale
    + { file: 'gsd-core\\workflows\\execute-plan.md', ... }

The remote runner this repo gates on is Linux-only and cannot see this class at
all; the GitHub Actions Windows lane is what caught it.

Normalization is unconditional — never gated on process.platform. A
platform-conditional normalizer makes the POSIX path the special case and
leaves the Windows branch unexercised on every other OS, which is the same
blind spot in a different place. It is applied at one seam inside
findPromptDrift, which builds `file` on every returned violation, so the
baseline key, the --update writer, the stderr report and the tests all consume
one normalized value.

The regression tests drive a Windows-shaped relPath directly and run on every
OS rather than skipping off-Windows — a test that only runs on the platform
where the bug lives is why this escaped. They include a sanity check that
un-normalized input does NOT match, so the assertion cannot pass vacuously.

Audited the three sibling guards: none keys against a committed cross-platform
baseline, and their exemption keys are path.join-built, so producer and
consumer share the native convention. Left correct code alone rather than
making them look alike. scripts/lib/drift-scan.cjs is untouched — normalizing
there would break those three on Windows.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

---------

Co-authored-by: sim <sim@local>
Co-authored-by: Claude Opus 5 <noreply@anthropic.com>

scripts/lint-milestone-window-drift.cjs

@@ -59,12 +59,26 @@
  * quoted/backticked strings (not shared — `lint-plan-count-drift.cjs` has no
  * equivalent need, since its own literal-bearing shape is regex-only).
  *
- * Owner file (exempt by construction): `src/roadmap-parser.cts` — it not only
- * DEFINES this grammar but composes `#{1,3}` with `(?!Phase...)`/marker
- * alternations at several internal call sites (`computeMilestoneSectionEnd`,
- * `locateMilestoneHeadings`, `extractCurrentMilestoneScoped`'s
- * `anyMilestonePattern`/`anyMilestoneOrDetails`) that are the canonical
- * implementation, not copies of it.
+ * Owner file: `src/roadmap-parser.cts` DEFINES this grammar, but it is NOT
+ * exempt as a whole file — that was the original design (a bare per-file
+ * allowlist) and it closed off exactly the blind spot ADR-3180 Decision 4(a)
+ * warns about: `getMilestoneInfo`, added later in this same owner file,
+ * hand-rolled its own milestone-heading regex (issues #3171, #3197) and the
+ * whole-file exemption made it invisible to this guard. The owner file is now
+ * scanned like every other file in SCAN_DIRS; only its named canonical
+ * functions are exempt (`FUNCTION_SCOPED_EXEMPTIONS`, keyed on `OWNER_FILE`),
+ * each with a written reason — `isMilestoneShippedInRoadmap`,
+ * `locateMilestoneHeadings`, `hasMilestoneSectioning`, and
+ * `extractCurrentMilestoneScoped` (whose `anyMilestonePattern`/
+ * `anyMilestoneOrDetails` locals compose `#{1,3}` with the `(?!Phase...)`/
+ * marker alternations as part of the canonical implementation, not a copy of
+ * it). `computeMilestoneSectionEnd` carries (a) and (b) on two DIFFERENT
+ * lines (the heading-quantifier match and the version/marker test are two
+ * separate statements) rather than one line carrying both, so this guard's
+ * own documented per-line-scan limit means it never fires there and it needs
+ * no listed exemption. An unrelated re-derivation added anywhere else
+ * in this file — including inside a function added after this guard, such as
+ * a future `getMilestoneInfo`-shaped one — is still caught.
  *
  * The tree-walk / root-confinement / regex-literal-tokenizer / sanitizer
  * machinery is SHARED with `scripts/lint-plan-count-drift.cjs` via
@@ -156,9 +170,35 @@ const OWNER_FILE = path.join('src', 'roadmap-parser.cts');
 //     does not itself carry token (b) as this guard defines it (no
 //     `(?!Phase` lookahead, no marker-emoji pairing) — this exemption
 //     currently documents intent rather than suppressing a live match.
+//   - roadmap-parser.cts isMilestoneShippedInRoadmap: composes the heading
+//     quantifier with the shipped/active MARKER check (via
+//     isClosedMilestoneHeading) to answer "is THIS milestone version marked
+//     shipped by the ROADMAP" — a documented, narrower question than
+//     computeMilestoneSectionEnd/locateMilestoneHeadings' "where does it
+//     end"/"which heading is it", not a copy of either.
+//   - roadmap-parser.cts locateMilestoneHeadings: this literally IS the
+//     canonical heading-locator this guard exists to protect (see the
+//     function's own header comment) — every other module's heading lookup
+//     is expected to call it, not re-express it.
+//   - roadmap-parser.cts hasMilestoneSectioning: the canonical "does this
+//     ROADMAP use milestone sectioning at all" predicate — a deliberately
+//     WEAKER, version-agnostic composition of the same two tokens, owned
+//     here per its own header comment so the milestone-heading vocabulary
+//     has one home rather than a third hand-rolled copy in state.cts.
+//   - roadmap-parser.cts extractCurrentMilestoneScoped: its
+//     `anyMilestoneOrDetails`/`anyMilestonePattern` locals are the two
+//     internal call sites the header comment already names as part of the
+//     canonical implementation (composing `#{1,3}` with the
+//     `(?!Phase...)`/marker alternations to find "the next milestone
+//     boundary" while assembling the current-milestone window) — not
+//     re-derivations of a question answered elsewhere.
 const FUNCTION_SCOPED_EXEMPTIONS = new Map([
   [path.join('src', 'roadmap-command-router.cts'), new Set(['checkW021'])],
   [path.join('src', 'verify.cts'), new Set(['checkMilestonePrefixMismatches'])],
+  [
+    OWNER_FILE,
+    new Set(['isMilestoneShippedInRoadmap', 'locateMilestoneHeadings', 'hasMilestoneSectioning', 'extractCurrentMilestoneScoped']),
+  ],
 ]);
 
 // Optional `export ` modifier, mirroring `lint-plan-count-drift.cjs`'s
@@ -287,10 +327,12 @@ function scanRepo(root) {
     scanExt: SCAN_EXT,
     onFile(rel, text) {
       // `rel` is already the REAL (canonical) path (scanTree resolves
-      // symlinks before calling onFile), so this comparison — and
+      // symlinks before calling onFile), so this — and
       // FUNCTION_SCOPED_EXEMPTIONS above, also keyed on `rel` — match
-      // consistently regardless of which symlink reached the file.
-      if (rel === OWNER_FILE) return [];
+      // consistently regardless of which symlink reached the file. The owner
+      // file is NOT short-circuited here; it is scanned like every other
+      // file, and only its named canonical functions are exempt (see
+      // FUNCTION_SCOPED_EXEMPTIONS).
       return findMilestoneWindowDrift(text, rel).map((d) => ({ file: rel, ...d }));
     },
   });