T-BQRU-quality-normalize-ports-pids-timings

Status: closed/done · Impact: medium · Complexity: small

Goal

The quality service’s baseline-diff finding normalization (normalizeFinding in plugin/lib/services/quality/baseline.ts, shipped by T-TWZD-normalize-baseline-diff-nondeterministic-output / PR #299) masks ephemeral tmpdir paths and transient commit SHAs, but NOT ephemeral ports, PIDs, or (Nms)-style timing tokens. Verbs like bun test, the dashboard server, and rumdl emit lines carrying those per-run-volatile tokens, so a line that is otherwise identical to its baseline counterpart never matches and surfaces as a false-positive new-drift in the baseline-diff gate (quality run --diff-against-baseline, the quality baseline diff op). This task closes that residual noise class by extending the same normalizeFinding masking pass with symmetric masks for those three token kinds.

A gap surfaced in the post-mortem of T-RVMG-adopt-moon-workspace-runner: “The quality service’s normalizeFinding masks tmpdir paths and SHAs (shipped by T-TWZD) but NOT ephemeral ports, PIDs, or timing tokens. So bun test (dashboard ephemeral port/PID) and rumdl (summary line (80ms) timing) still trip false-positive new-drift in the Step 7 baseline-diff gate on any branch. Extend normalizeFinding with symmetric masks for ports, PIDs, and (Nms)/timing tokens, building on T-TWZD’s tmpdir+SHA masking.”

— T-RVMG-adopt-moon-workspace-runner

Today

Location	Role today
plugin/lib/services/quality/baseline.ts#normalizeFinding	The pure masking pass. Masks, in fixed order: (1) absolute tmpdir roots (/tmp, /private/tmp, $TMPDIR) plus their randomized subpath → <TMPDIR>; (2) bare 7-40-char lowercase-hex commit SHAs (boundary-anchored) → <SHA>. It does NOT touch ports, PIDs, or timing tokens, so a finding line carrying :54321, pid 12345, or (123ms) stays unique per run.
plugin/lib/services/quality/baseline.ts#diff	The per-verb set-difference. Maps both current and baseline finding lists through normalizeFinding before the comparison (symmetric masking), so adding a new mask to normalizeFinding automatically applies to both sides here — no diff-site change needed.
plugin/lib/services/quality/baseline.ts#escapeRegExp	Helper used by the tmpdir mask; available for reuse, though the new masks are static regexes that don’t need it.
plugin/lib/services/quality/ops/baseline/diff.ts	The quality baseline diff op handler — calls diff() and surfaces newDrift / gatePass. Consumes the masked output; no change needed.
plugin/lib/services/quality/ops/run.ts	The quality run --diff-against-baseline gate path. Emits new-drift: <verb>: <line> from the masked diff output; no change needed.
plugin/lib/services/quality/run-checks.ts	The legacy run --diff-against-baseline forwarder; emits the same new-drift: lines from the masked diff output. No change needed.
plugin/lib/services/quality/tests/quality_ops.test.ts	The bun:test suite for the quality ops, including the baseline diff roundtrip cases. There is no dedicated normalizeFinding unit test today; the masking is exercised only indirectly. This is where the new masking unit tests land.

A finding line containing an ephemeral port (:54321), a PID (pid 12345), or a (123ms) timing token is unique per run, so it is always in the per-verb set-difference and always surfaces as a false-positive new-drift finding — the same mechanism T-TWZD fixed for tmpdir paths and SHAs, on the three token kinds T-TWZD explicitly left out.

Proposed

normalizeFinding masks three further ephemeral token kinds, appended after the existing tmpdir and SHA masks (fixed, documented order preserved), each boundary-anchored to avoid clobbering unrelated content:

• Ephemeral ports — a : immediately followed by a port number in the ephemeral range and not part of a longer numeric token (e.g. 127.0.0.1:54321, localhost:49200, a bare :50000 in a URL) → :<PORT>. Scope the match to the dynamic/ephemeral range (ports >= 1024, i.e. 4-5 digit port numbers) so stable well-known ports a finding might legitimately assert (:80, :443) are left intact; the dashboard server and bun test listeners bind ephemeral ports, which is the volatile class this targets.
• PIDs — the token pid (case-insensitive, whole word) followed by optional whitespace/=/: and a 1-7-digit run → pid <PID> (preserving the separator shape, the digits replaced by <PID>). Anchoring on the literal pid keyword avoids masking arbitrary integers that merely look PID-shaped.
• Timing tokens — a parenthesized duration (<N>ms) / (<N>s) / (<N.N>ms) etc. (an integer or decimal magnitude immediately followed by a recognized time unit ms/s/µs/us/ns, inside parentheses) → (<TIME>). This is the rumdl summary-line (80ms) shape and the common bun test per-suite (123ms) shape.

As with the existing masks, the new ones are applied symmetrically at diff time (both operands of the set-difference pass through normalizeFinding in diff()), so two lines differing only in one of these tokens collapse to the same masked string and cancel out, while a line whose real content changed still differs after masking and is still reported. The on-disk baseline format is unchanged — findings stay captured verbatim; masking remains a diff-time concern.

Approach

1. Extend normalizeFinding in plugin/lib/services/quality/baseline.ts with three new masking steps appended after the existing SHA mask (step 2), keeping the fixed, documented order: 3. ephemeral ports → :<PORT>; 4. PIDs → pid <PID>; 5. timing tokens → (<TIME>). Each is a static, boundary-anchored String.prototype.replace with a global regex, mirroring the existing step-2 SHA mask style.
   • Port regex: match a : preceded by a host/IP/word boundary and followed by a 4-5-digit run (>= 1024) that is not itself followed by another digit — e.g. /(?<![0-9]):(\d{4,5})(?![0-9])/g → :<PORT>. (4-5 digits keeps well-known 1-3-digit ports like :80/:443 unmasked.)
   • PID regex: match pid case-insensitively as a whole word, an optional separator (\s+, =, or : with optional surrounding space), then a 1-7-digit run — replace the digit run with <PID> while preserving the keyword and separator (e.g. /\bpid(\s*[:=]?\s*)\d{1,7}\b/gi → `pid$1<PID>`, normalizing the captured separator if needed so the placeholder is stable).
   • Timing regex: match a parenthesized magnitude-plus-unit token — /\((\d+(?:\.\d+)?)\s?(ms|s|µs|us|ns)\)/g → (<TIME>).
2. Update the normalizeFinding JSDoc (the “Masks, in fixed order:” list in baseline.ts) to enumerate the three new masks (3 ports, 4 PIDs, 5 timings) alongside the existing tmpdir/SHA entries, so the comment stays an accurate inventory of the masking pass.
3. Add normalizeFinding unit tests in plugin/lib/services/quality/tests/quality_ops.test.ts (a new describe("normalizeFinding masks ephemeral ports, PIDs, timings", ...) block importing normalizeFinding directly from the plugin/lib/services/quality/baseline.ts module (a relative import from the test dir up to the baseline module):
   • a line serving on 127.0.0.1:54321 masks to serving on 127.0.0.1:<PORT>;
   • a line worker pid 12345 started masks to worker pid <PID> started;
   • a line linted 40 files (80ms) masks to linted 40 files (<TIME>);
   • a negative case asserting :443 / :80 and a 1-3-digit non-ephemeral port are left unmasked, and an integer not preceded by pid is left unmasked.
4. Add a diff-level regression test in the same suite (mirroring T-TWZD’s tmpdir-only difference cancels out case): a current finding and a baseline finding differing only in a port / PID / timing token yield an empty per-verb diff (no new-drift); and a companion case where the non-ephemeral part genuinely differs still reports the line after masking (no false negative).
5. Run the suite — bun test against plugin/lib/services/quality/tests/quality_ops.test.ts — and the local quality checks to confirm the new masks behave and nothing regressed.

Files to touch

Location	Kind	Change
plugin/lib/services/quality/baseline.ts	modify	Extend normalizeFinding with masks 3 (ephemeral ports → :<PORT>), 4 (PIDs → pid <PID>), and 5 (timing tokens → (<TIME>)), appended after the existing SHA mask; update the JSDoc fixed-order inventory.
plugin/lib/services/quality/tests/quality_ops.test.ts	modify	Add a normalizeFinding unit-test block (positive masks for port/PID/timing plus negative cases for well-known ports and bare integers) and a diff-level case asserting a port/PID/timing-only difference cancels out while a genuine change still surfaces.

Acceptance criteria

• AC-1: normalizeFinding("serving on 127.0.0.1:54321") returns "serving on 127.0.0.1:<PORT>"; normalizeFinding("worker pid 12345 started") returns "worker pid <PID> started"; normalizeFinding("linted 40 files (80ms)") returns "linted 40 files (<TIME>)" — each asserted by a bun:test case in plugin/lib/services/quality/tests/quality_ops.test.ts.
• AC-2: A bun:test case asserts the new masks do NOT over-reach: a well-known port (:443, :80) and a bare integer not preceded by pid are returned unchanged by normalizeFinding.
• AC-3: A diff-level bun:test case in which the current and baseline findings for a verb differ ONLY in an ephemeral port, a PID, or a (Nms) timing token yields an empty per-verb diff (zero new-drift), where today it yields one false-positive line.
• AC-4: A companion diff-level case in which the non-ephemeral portion of a finding genuinely changed still reports that line as new-drift after masking (no false negative introduced).
• AC-5: The existing tmpdir and SHA masks (T-TWZD) still pass — the new masks are appended, not substituted; the bun:test suite at plugin/lib/services/quality/tests/quality_ops.test.ts is green, including the pre-existing baseline diff roundtrip cases.

Out of scope

• The count-summary / corpus-growth drift dimension (audit - OK enumeration rows, OK N/N counts, file-count headers that shift run-to-run independent of any ephemeral token) — owned by T-BCNP-quality-gate-ignores-summary-and-corpus-lines (planning/backlog), exactly as T-TWZD scoped it out. This task does not duplicate or pre-empt that approach decision.
• Changing the on-disk baseline capture format. Findings stay captured verbatim; masking remains a diff-time concern applied symmetrically in diff().
• Masking timestamps, memory addresses, or other ephemeral token classes not named here. The three kinds in scope are the ones the T-RVMG-adopt-moon-workspace-runner post-mortem observed; new classes get their own follow-up if they surface.

Dependencies

• none

Discovery context

Spawned by /sdlc:spawn-task-pr on 2026-06-17 UTC from T-RVMG-adopt-moon-workspace-runner in git@github.com:sksizer/dev.git.

Builds on T-TWZD-normalize-baseline-diff-nondeterministic-output (closed/done, PR #299), which added normalizeFinding masking for tmpdir paths and SHAs but explicitly did not cover ports, PIDs, or timing tokens.

Dedup search (spawn-from-post-mortem)

Bullet: Step 7 false-flagged 1 new-drift on the rumdl summary line’s (63ms) timing token; the 9 underlying MD013 issues in untouched T-XBJY all subtracted as pre-existing — normalizeFinding does not mask timing tokens. Keywords searched: normalizefinding, false-flagged, pre-existing, underlying, subtracted, new-drift, untouched, summary Excluded: T-F31Q-migrate-site-to-bun Top candidates (score / status / headline):

• 89 / closed/done / T-TWZD-normalize-baseline-diff-nondeterministic-output — run_quality_checks —diff-against-baseline masks ephemeral tmpdir paths and transient SHAs before line-diffing
• 45 / planning/backlog / T-BCNP-quality-gate-ignores-summary-and-corpus-lines — quality-gate ignores baseline-shifting summary and corpus-growth lines
• 40 / closed/done / T-H69K-run-quality-checks-isolates-pre-existing-drift — run_quality_checks.py only fails on drift the current branch introduced
• 37 / open/ready / T-BQRU-quality-normalize-ports-pids-timings — normalizeFinding masks ephemeral ports, PIDs, and timing tokens before baseline-diff
• 22 / closed/done / T-F8BP-dogfood-baseline-smoke-test — Dogfood smoke-test script for new quality-check verbs before declaring done Decision: SPAWNED → overridden to LINKED-EXISTING Rationale: This task (T-BQRU, rank #4 by score) is the exact active tracker for the gap — its headline is “normalizeFinding masks ephemeral ports, PIDs, and timing tokens before baseline-diff”, verbatim this bullet’s (63ms) timing-token false-drift. The score-based top hit T-TWZD is closed/done and explicitly deferred timing tokens to this task. Linked from T-F31Q-migrate-site-to-bun.

Bullet: The baseline line-diff flags rumdl’s summary line ‘Issues: Found N issues in M/K files (XXms)’ as new-drift because the (XXms) timing is non-deterministic — a phantom new-drift=1 with zero real findings changed. Fix: the differ should strip trailing (\d+ms) timings (or exclude per-runner summary lines) before diffing. Same baseline-isolation class T-XBJY’s own post-mortem already flagged. Keywords searched: baseline-isolation, non-deterministic, per-runner, line-diff, new-drift, baseline, findings, trailing, timing, rumdl Excluded: T-VE7H-task-work-probe-keys-package-manager-off-project Top candidates (score / status / headline):

• 123 / closed/done / T-TWZD-normalize-baseline-diff-nondeterministic-output — masks ephemeral tmpdir paths and transient SHAs before line-diffing
• 64 / open/ready / T-BQRU-quality-normalize-ports-pids-timings — normalizeFinding masks ephemeral ports, PIDs, and timing tokens before baseline-diff
• 40 / planning/backlog / T-BCNP-quality-gate-ignores-summary-and-corpus-lines — quality-gate ignores baseline-shifting summary and corpus-growth lines Decision: SPAWNED → overridden to LINKED-EXISTING T-BQRU-quality-normalize-ports-pids-timings Rationale: The script’s top hit T-TWZD (closed/done) is the predecessor that added tmpdir+SHA masking but explicitly scoped OUT ports/PIDs/timings. T-BQRU (open/ready, rank #2) is the live successor that adds exactly the (Nms) timing-token mask this bullet asks for — its Goal quotes “rumdl (summary line (80ms) timing) … false-positive new-drift” verbatim. Linking to the active owner rather than spawning a third coverage of the same masking gap. Originating task: T-VE7H-task-work-probe-keys-package-manager-off-project

Dedup search (spawn-from-post-mortem)

Bullet: The baseline-gated gate reported new-drift=10, all of it bun test ephemeral stdout (random http://127.0.0.1:/ ports, PIDs, and example PR URLs from the parallel T-CW4K dashboard tests) — normalizeFinding masks neither the URL port nor bare PID columns, so the lines mismatch the baseline and surface as false new-drift that FAILS an unrelated task’s gate. Keywords searched: normalizefinding, baseline-gated, new-drift, ephemeral, dashboard, unrelated, reported, parallel Excluded: T-H7LB-task-work-appends-post-mortem-stub Top candidates (score / status / headline):

• 77 / closed/done / T-TWZD-normalize-baseline-diff-nondeterministic-output — run_quality_checks —diff-against-baseline masks ephemeral tmpdir paths and transient SHAs before line-diffing
• 67 / open/ready / T-BQRU-quality-normalize-ports-pids-timings — normalizeFinding masks ephemeral ports, PIDs, and timing tokens before baseline-diff
• 49 / open/ready / T-JDEV-dashboard-build-into-plugin — Build-into-plugin pipeline: committed drift-gated web-dist; retire INDEX_HTML
• 43 / in-progress / T-CW4K-scaffold-dashboard-vite-vue — Scaffold apps/dashboard (Vite + Vue 3) with one-command backend+frontend dev startup
• 43 / open/ready / T-JZL4-generate-dashboard-api-client — Generate a typed API client for the dashboard frontend in packages/ts Decision: LINKED-EXISTING T-BQRU (script said SPAWNED → overridden) Rationale: T-BQRU (rank #2, score 67, open/ready) is the exact active tracker — its headline is “normalizeFinding masks ephemeral ports, PIDs, and timing tokens before baseline-diff”, verbatim this bullet’s port/PID false-drift. The script’s #1 hit T-TWZD is closed/done and explicitly deferred these token kinds to T-BQRU. Spawning would duplicate the same tracker. New data point this post-mortem adds: the unmasked ports/PIDs no longer just add cosmetic noise — the resulting false new-drift FAILED an unrelated task’s Step 7 baseline-diff gate (10 false findings from the parallel T-CW4K dashboard tests’ ephemeral ports, PIDs, and example PR URLs), making this a concrete cross-task gate-blocker. The example PR URL class is a fourth ephemeral token kind beyond T-BQRU’s current three (ports/PIDs/timings) — worth weighing into T-BQRU’s scope when it is implemented. Linked from: T-H7LB-task-work-appends-post-mortem-stub

Dedup search (spawn-from-post-mortem)

Bullet: bun test’s dashboard server test prints a live-PID sdlc dashboard list table row that the quality runner’s normalizer does not mask, so it surfaces as a non-deterministic new-drift bun test finding on every run, already tracked by T-BQRU-quality-normalize-ports-pids-timings. Keywords searched: t-bqru-quality-normalize-ports-pids-timings, non-deterministic, normalizer, dashboard, new-drift, live-pid, surfaces, quality Excluded: T-JZL4-generate-dashboard-api-client Top candidates (score / status / headline):

• 80 / closed/done / T-TWZD-normalize-baseline-diff-nondeterministic-output — run_quality_checks —diff-against-baseline masks ephemeral tmpdir paths and transient SHAs before line-diffing
• 74 / open/ready / T-BQRU-quality-normalize-ports-pids-timings — normalizeFinding masks ephemeral ports, PIDs, and timing tokens before baseline-diff
• 57 / closed/done / T-CW4K-scaffold-dashboard-vite-vue — Scaffold apps/dashboard (Vite + Vue 3) with one-command backend+frontend dev startup
• 54 / planning/needs-definition / T-44OO-plugin-scripts-self-discover-project-root — Plugin scripts self-discover project root from cwd
• 49 / open/ready / T-JDEV-dashboard-build-into-plugin — Build-into-plugin pipeline: committed drift-gated web-dist; retire INDEX_HTML Decision: LINKED-EXISTING T-BQRU-quality-normalize-ports-pids-timings (script said SPAWNED — overridden) Linked from: T-JZL4-generate-dashboard-api-client Rationale: The bullet itself names T-BQRU as the tracker, and T-BQRU (open/ready, rank #2) is exactly the live owner — its Goal names the dashboard server’s ephemeral PID as a residual noise class the normalizeFinding mask must cover. The script chose SPAWNED only because its #1 hit T-TWZD is closed/done (the predecessor that masked tmpdir/SHAs but explicitly scoped OUT ports/PIDs/timings). Linking to the active owner rather than spawning a third coverage of the same masking gap.

Dedup search (spawn-from-post-mortem)

Bullet: The baseline-gated quality gate reported 3 false-positive new-drift findings — a bun test dashboard line whose PID is not normalized (24505 vs the baseline’s 89733), and two rumdl summary-count lines (Found 30 issues in 10/648 files) that shifted only because this branch legitimately deleted one markdown file (tests/parity/README.md), changing the file-count denominator. The gate’s output normalizer should also mask process IDs and treat tool summary/count lines (issue counts, N/M files) as non-gating, so a legitimate file deletion or a non-deterministic PID does not surface as new drift. Keywords searched: non-deterministic, baseline-gated, false-positive, summary-count, legitimately, denominator, normalized, file-count Excluded: T-T3QJ-retire-tests-parity-harness Top candidates (score / status / headline):

• 26 / closed/done / T-TWZD-normalize-baseline-diff-nondeterministic-output — run_quality_checks —diff-against-baseline masks ephemeral tmpdir paths and transient SHAs before line-diffing
• 13 / open/ready / T-BQRU-quality-normalize-ports-pids-timings — normalizeFinding masks ephemeral ports, PIDs, and timing tokens before baseline-diff
• 9 / closed/done / T-0012 — Extract _common.json fragment; refactor per-type schemas to $ref it
• 9 / planning/draft / T-7AR0-orchestrate-change-detection-watch-command — sdlc orchestrate watch — deterministic pending-work gate so /sdlc:orchestrate wakes only when there is actionable work
• 9 / closed/done / T-VE7H-task-work-probe-keys-package-manager-off-project — task-work permissions probe should key package-manager signal off project verbs, not blanket npm

Decision: LINKED-EXISTING T-BQRU-quality-normalize-ports-pids-timings (script said SPAWNED → overridden) Linked from: T-T3QJ-retire-tests-parity-harness Rationale: This bullet straddles two open trackers. T-BQRU (rank #2, open/ready) is the live owner of the PID-normalization facet — “a bun test dashboard line whose PID is not normalized (24505 vs … 89733)” is verbatim the normalizeFinding PID mask T-BQRU adds. The script’s #1 hit T-TWZD is closed/done and explicitly deferred ports/PIDs/timings to T-BQRU. The same bullet’s summary/count-line facet (the rumdl “Found 30 issues in 10/648 files” lines shifting on a legitimate markdown-file deletion) is linked separately to its owner T-BCNP-quality-gate-ignores-summary-and-corpus-lines. Linked to both rather than spawning a duplicate of either masking concern. Originating task: T-T3QJ-retire-tests-parity-harness

Dedup search (spawn-from-post-mortem)

Bullet: Step 7’s baseline-gated quality run reported one false-positive new-drift: line — a dashboard test prints a non-deterministic PID (/private http://127.0.0.1:/); the baseline normalizer scrubs TMPDIR and PORT but not the PID, so the line differs run-to-run and masquerades as branch-introduced drift on a branch that touches only model/entity.ts. The quality baseline normalizer should scrub process-ephemeral integers (PIDs) the way it already scrubs temp paths and ports. Keywords searched: non-deterministic, branch-introduced, process-ephemeral, baseline-gated, false-positive, masquerades, normalizer, run-to-run Excluded: T-ZGO4-rebase-parse-operations-table-on-markdown-contract Top candidates (score / status / headline):

• 26 / closed/done / T-TWZD-normalize-baseline-diff-nondeterministic-output — run_quality_checks —diff-against-baseline masks ephemeral tmpdir paths and transient SHAs before line-diffing
• 21 / open/ready / T-BQRU-quality-normalize-ports-pids-timings — normalizeFinding masks ephemeral ports, PIDs, and timing tokens before baseline-diff
• 10 / planning/backlog / T-BCNP-quality-gate-ignores-summary-and-corpus-lines — quality-gate ignores baseline-shifting summary and corpus-growth lines
• 9 / closed/done / T-VE7H-task-work-probe-keys-package-manager-off-project — task-work permissions probe should key package-manager signal off project verbs, not blanket npm
• 8 / planning/draft / T-XB7F-task-work-step6-briefs-baseline-gated-quality — task-work Step 6 briefs the implementer with the baseline-gated quality invocation Decision: SPAWNED → overridden to LINKED-EXISTING T-BQRU-quality-normalize-ports-pids-timings Rationale: T-BQRU (rank #2, open/ready) is the exact active tracker — its headline is “normalizeFinding masks ephemeral ports, PIDs, and timing tokens before baseline-diff” and its Goal names the dashboard server’s ephemeral PID as a residual noise class the normalizeFinding mask must cover, verbatim this bullet’s <pid> false-drift. The script’s #1 hit T-TWZD is closed/done and explicitly deferred ports/PIDs/timings to T-BQRU. Linking to the active owner rather than spawning a duplicate of the same masking gap. Originating task: T-ZGO4-rebase-parse-operations-table-on-markdown-contract

Post-mortem

Captured by /sdlc:task-work on 2026-06-30. PR: pending.

Acceptance criteria coverage

TBD — filled at Step 8.

What worked

TBD — filled at Step 8.

Friction and automation gaps

TBD — filled at Step 8.

---

← Back to Tasks