@vyuhlabs/dxkit 2.4.7 → 2.5.0

package/CHANGELOG.md

@@ -7,6 +7,432 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.5.0] - 2026-05-18
+
+### Summary
+
+2.5.0 introduces **commit-time guardrails** — a per-finding baseline
+captured once on a brownfield repo, then diffed against every
+subsequent scan to detect net-new regressions while grandfathering
+existing debt. Existing issues stay where they are, new ones block.
+
+This release also **prunes the legacy task-runner scaffolding** that
+prior versions of `init --full` bundled (Makefile, `.project/` task
+scripts, `.ai/` prompt scaffolding, per-language config templates,
+non-dxkit CI workflows, `.editorconfig`, `.pre-commit-config.yaml`).
+The agent DX surface is now the sole `init --full` output —
+`init --full` lands 73 files (down from 119), every one of them
+focused on equipping AI coding agents to operate safely on the
+codebase. Customers who relied on the legacy scaffolding can use
+`@vyuhlabs/create-devstack` for greenfield project bootstrap.
+
+The release ships three coordinated surfaces:
+
+1. **A new `baseline` / `guardrail` CLI** that captures stable
+   per-finding identities, diffs current scans against them, and
+   classifies each pair (`added` / `relocated` / `tooling_drift` /
+   `config_drift` / `persisted` / `removed` / `fixed`) with a
+   confidence score and structured reasons. The classifier ships
+   with a **scanner-wobble demotion** that converts `added` findings
+   on UNCHANGED lines into `uncertain` (warn) for high-wobble kinds
+   (`code`, `hygiene`), so semgrep's per-run non-determinism on
+   large codebases doesn't trigger false-positive blocks. Findings
+   inside the diff's changed lines still block — real regressions
+   are caught. Customers can extend or clear the kind list via
+   `addedRequiresChangedLines` in `.dxkit/policy.json`.
+2. **Init-installable templates** for the pre-push guardrail hook,
+   a devcontainer with pinned toolchains + Claude Code & Codex
+   CLIs, a GitHub Actions PR-gate workflow that posts a markdown
+   summary as a PR comment, and a post-merge baseline-refresh
+   workflow that keeps the anchor current. Pre-commit + AI-PR-
+   review are opt-in via `--with-precommit-hook` and
+   `--with-pr-review` respectively (slow on large repos / requires
+   API-cost opt-in). Every `init` also seeds `.gitignore` entries
+   for the analyzer runtime outputs (`.dxkit/reports/`,
+   `.dxkit/dashboard.html`) and writes a starter `.dxkit-ignore`
+   template for dxkit-specific scan-exclusion tuning.
+3. **Aggregate-gate flags** (`--fail-on-score`, `--fail-on-severity`)
+   on every analyzer command, plus a stable JSON schema banner on
+   every `--json` output so consumers can version-gate.
+
+Tests: ~1530 unit + integration cases pass on the integrated branch
+(up from 1265 at the 2.4.8 baseline; +265 across fingerprinting,
+producers, policy, matcher, ship installers, the smart classifier,
+opt-in hook + workflow installers, and the CLI surface).
+
+#### New CLI surface
+
+```bash
+vyuh-dxkit baseline create [path] [--name <name>] [--force]
+                                  [--verbose]
+vyuh-dxkit baseline show   [path] [--name <name>] [--baseline <p>]
+                                  [--kind <kind>] [--json]
+vyuh-dxkit guardrail check [path] [--name <name>] [--baseline <p>]
+                                  [--changed-only] [--policy <p>]
+                                  [--json | --markdown]
+```
+
+- `baseline create` runs every analyzer, fingerprints each per-
+  finding entity through the canonical identity dispatcher
+  (`src/baseline/finding-identity.ts`), and writes
+  `.dxkit/baselines/<name>.json`. Schema-versioned
+  (`dxkit-baseline/v1`); commit it.
+- `baseline show` pretty-prints the on-disk baseline, optionally
+  filtered by kind or emitted as a schema-banner-wrapped JSON.
+- `guardrail check` loads the baseline, re-runs the analyzers,
+  matches via the git-aware matcher (`-M` renames, ±2 line fuzz,
+  content-hash fallback for shallow clones), classifies each pair
+  through the brownfield policy, and exits 1 when the policy
+  blocks. Output modes: console (default), `--json` (schema
+  `dxkit.guardrail-check.v1`), or `--markdown` (used by the PR-
+  gate workflow to post a comment).
+
+The full read/write/compare triplet flows through a registered
+producer pipeline (`src/baseline/producers/index.ts:PRODUCERS`) —
+adding a new identity kind means registering a producer, not
+editing the orchestrator. Architectural rule documented in
+`CLAUDE.md` Rule 10 with three enforcement gates (arch check +
+contract test + synthetic-producer playbook).
+
+#### Aggregate gates + schema banner
+
+Every analyzer command (`health`, `test-gaps`, `quality`,
+`vulnerabilities`, `bom`) gains composable exit-code gates:
+
+- `--fail-on-score <N>` — exit 1 when the headline score drops
+  below N (applies to `health`, `test-gaps`).
+- `--fail-on-severity <tier>` — exit 1 when any finding at `<tier>`
+  or higher exists (applies to `vulnerabilities`, `bom`; tier ∈
+  critical / high / medium / low).
+
+Every `--json` output carries a top-level
+`schema: 'dxkit.<kind>-report.v1'` banner so consumers can version-
+gate against future schema migrations.
+
+#### `vyuh-dxkit init` ship flags
+
+`init` gains four new flags, all implied by `--full`:
+
+- `--with-hooks` writes `.githooks/pre-commit` (fast,
+  `--changed-only`) and `.githooks/pre-push` (full).
+- `--with-devcontainer` writes a lightweight `.devcontainer/`
+  layering all seven supported language toolchains via devcontainer
+  features + a `post-create.sh` that runs `vyuh-dxkit tools install
+  --yes` to provision the scanner toolchain pinned in the registry
+  + `install-agent-clis.sh` that installs Claude Code + OpenAI
+  Codex CLIs (opt out of either with `CLAUDE_CODE_VERSION=skip` /
+  `CODEX_VERSION=skip`).
+- `--with-ci` writes `.github/workflows/dxkit-guardrails.yml` (PR-
+  gate that posts a markdown summary as a PR comment, updating in
+  place across pushes via an HTML marker).
+- `--with-baseline-refresh` writes
+  `.github/workflows/dxkit-baseline-refresh.yml` (regenerates the
+  baseline on every push to the consumer's default branch and
+  auto-commits with `[skip ci]`). The default-branch name is
+  detected at install time from the consumer's git state, with
+  fallbacks for `main` / `master` / `trunk` / `develop`.
+
+Installs are **additive by default**. Existing `.githooks/<hook>`
+or `.husky/<hook>` files trigger a `.dxkit` sidecar + merge note
+instead of an overwrite. An existing `.devcontainer/devcontainer.json`
+stashes the full dxkit set under `.devcontainer/.dxkit-reference/`
+for manual merge. Workflow files are uniquely named so they don't
+collide; if our exact filename already exists, init skips it. The
+`--force` flag overrides every additive fallback and writes in
+place.
+
+#### Brownfield policy
+
+`.dxkit/policy.json` (auto-discovered at the repo root) tunes which
+classifications block vs warn, per-severity confidence thresholds
+that demote low-quality matches to `uncertain`, and per-finding-kind
+block rules (`newSecret`, `newCriticalSecurity`,
+`newCriticalDependencyVulnerability`, etc.). Compiled-in defaults
+ship a conservative posture: block on `added`, warn on
+`tooling_drift` / `config_drift` / `newly_detected` /
+`probable_existing` / `uncertain`. The `--policy <path>` flag
+overrides auto-discovery; when no policy is found, the defaults
+apply.
+
+#### Architectural fixes surfaced by the customer-repo audit
+
+A pre-ship audit on three real customer repositories (a 444-source
+TypeScript backend, a 553-source TypeScript frontend, and a
+.NET WinForms project) surfaced four drift classes between the
+report aggregates and the per-finding identity sets the baseline
+captures. All four are closed in 2.5.0:
+
+1. **Large-file producer was capped at top 10.** The gather layer
+   pre-sliced `largestFiles` to ten entries for the markdown
+   renderer's "Top Files by Size" table; the baseline producer
+   inherited the cap and silently dropped per-file identity for
+   every oversized file beyond the first ten. A real customer
+   brownfield with 47 files over 500 lines saw 10 baseline entries;
+   the .NET project with 926 oversized files saw 10. The gather now
+   emits every file over the 500-line threshold sorted descending;
+   the renderer adds an explicit `.slice(0, 10)` at the table site.
+   `HealthMetrics.filesOver500Lines` aggregate now matches the
+   per-kind count in the baseline byte for byte. Combined recovery
+   across the three audit repos: 1,087 previously-silently-missed
+   `large-file` findings now flow into baselines.
+
+2. **Secret-HMAC producer emitted duplicates.** When the same
+   secret value appeared at multiple locations — the same token on
+   two lines of one file, a leaked key in both `.env` and
+   `src/config.ts`, or two overlapping gitleaks rules firing on the
+   same line — the producer wrote multiple entries with identical
+   `(rule, hmac)` identity. Identity sets aren't supposed to have
+   duplicates by definition. Now a per-call `Set<string>` keyed on
+   the computed identity collapses repeats; first write wins,
+   output order is stable.
+
+3. **Tools-map version probes occasionally cached `'present'`
+   under load.** The per-process version cache locks the first
+   probe's outcome to keep `toolchainHash` byte-stable across two
+   back-to-back gathers (a previously-shipped flake closure). But
+   when the first `execSync(<tool> --version)` raced its 5-second
+   timeout under heavy CPU load — parallel scanner pools or the
+   post-merge workflow doing two scans in series — the cache locked
+   the `'present'` fallback for the rest of the process. The tools
+   map in the baseline file then read `gitleaks@present` instead of
+   a real version, and the next run flagged spurious tooling-drift.
+   The fix retries the version probe up to three times before
+   falling back; each attempt is fresh. The cache layer is
+   unchanged — once a value settles (real version or genuine
+   `'present'`), it's locked for the rest of the process.
+
+4. **TypeScript license enrichment could stall the entire licenses
+   capability.** `gatherTsLicensesResult` calls `enrichReleaseDates`
+   after license-checker returns to populate the optional
+   `releaseDate` field from the npm registry. The enrichment runs
+   with 20-way concurrency, 10s per request — usually fast — but a
+   flaky network or rate-limited registry can push a 700-package
+   run past the dispatcher's 720-second deadline. When that
+   happens, the entire licenses capability is dropped and the
+   baseline silently loses every license entry. On the TypeScript
+   frontend audit repo, license-checker itself returned 749KB of
+   JSON in under 10 seconds when invoked manually; the enrichment
+   stalled the whole capability. Now the enrichment is raced
+   against a 60-second wall-clock budget; on timeout, the license
+   findings still emit with their static fields and `releaseDate`
+   is left unset on the unenriched ones. A previously-zero baseline
+   now captures 1,897 license entries on that repo.
+
+Together these four fixes recover **~3,000 baseline findings** that
+were being silently dropped on real customer repos pre-2.5.0.
+
+#### Migration guidance for 2.4.x users
+
+No breaking changes. Existing analyzer commands continue to work
+exactly as before. The new commands and flags are additive.
+
+To start using guardrails on an existing repo:
+
+```bash
+vyuh-dxkit init --with-hooks --with-ci --with-baseline-refresh
+git config core.hooksPath .githooks
+vyuh-dxkit baseline create
+git add .dxkit/baselines/main.json .githooks .github/workflows/dxkit-*.yml
+git commit -m "chore: enable dxkit guardrails"
+```
+
+See [`docs/getting-started.md`](docs/getting-started.md),
+[`docs/commands/baseline.md`](docs/commands/baseline.md),
+[`docs/commands/guardrail.md`](docs/commands/guardrail.md), and
+[`docs/configuration/policy.md`](docs/configuration/policy.md) for
+the full walkthrough.
+
+## [2.4.8] - 2026-05-18
+
+### Summary
+
+Focused patch release closing the regressions surfaced by a
+post-2.4.7 user-simulation evaluation across the three external
+audit repos. The biggest item is the structural follow-up to
+D134 — the silent-health failure root-caused in 2.4.7 was a
+real abandoned-Promise inside `runDetached`, but the underlying
+class (unbounded await chain at the dispatcher level) had a
+second failure mode that the 2.4.7 fix didn't reach. 2.4.8
+closes it structurally. Plus: a date-rollover false-failure on
+long runs, a Tools-used footer attribution drift, a cascade
+warning when the analysis cache can't be built, and a README
+upgrade-advisory correction. Tests: 1265 / 0 (up from 1241 at
+the 2.4.7 baseline).
+
+#### Per-provider deadline closes a second silent-health failure mode (D141)
+
+D134 in 2.4.7 added a `settle()` guard plus a safety deadline
+**inside** `runDetached` so that exit / error / safety-deadline
+each force the subprocess Promise to resolve. That closed the
+shape where a `runDetached` Promise itself stayed pending. But
+a post-ship user-simulation reproduced the same silent-rc=0
+behavior on a JS-heavy customer frontend audit — and this time
+the runDetached safety deadline did not fire, because the
+abandoned Promise was not inside `runDetached` at all. It was
+inside the capability dispatcher's `Promise.allSettled` over
+nine providers: one of those providers' `gatherOutcome` chains
+contained a Promise that never settled, `Promise.allSettled`
+cannot collapse an unsettled Promise, the whole
+`gatherCapabilityReport` stayed pending forever, Node's event
+loop emptied and the parent saw a clean rc=0 with no markdown
+written.
+
+Fix (commit `611321d`):
+
+- New `src/analyzers/tools/deadline.ts` with a
+  `withDeadline(promise, deadlineMs)` helper that races any
+  Promise against a timer.
+- The dispatcher (`src/analyzers/dispatcher.ts`) wraps every
+  provider's `gather` / `gatherOutcome` call in a 720-second
+  deadline (`DEFAULT_PROVIDER_DEADLINE_MS`). A stalled provider
+  is materialised as a skipped source with reason
+  `"stalled at >Ns (deadline)"` that flows through the existing
+  availability machinery into the `Tools unavailable` surface.
+  A stderr line names the stalled capability + source so the
+  abandoned-Promise location is visible in `--verbose` and CI
+  logs.
+- The two non-dispatcher gathers
+  (`gatherDepVulnsWithAvailability` and
+  `gatherLicensesWithAvailability`) iterate active packs
+  themselves; both apply the same per-pack deadline pattern.
+- New `DispatcherOptions` fields (`providerDeadlineMs`,
+  `onProviderStall`) so tests can wrap deadlines around 50-ms
+  stubs without polluting test output. Default `onProviderStall`
+  emits the stderr notification.
+- New regression test
+  (`test/dispatcher-deadline.test.ts`, 7 cases) exercises the
+  helper directly, the dispatcher with one hung + one good
+  provider, the all-hung case, the bounded wall-clock claim,
+  and confirms thrown-provider rejections still route through
+  `onProviderError` (not `onProviderStall`).
+
+Verification on the failure repo:
+
+- Pre-fix (2.4.7 user-sim): `report` exited 1 after ~1428 s;
+  Health step hung in the capabilities Promise.all and never
+  wrote `health-audit-*.md`; orchestrator's 2.4.7
+  defense-in-depth guard surfaced the ✗ but the underlying
+  hang remained.
+- Post-fix: `report` exited 0 in 1264.5 s; all 8 steps wrote
+  their reports; one stderr line attributed the stall to the
+  typescript-pack licenses provider walking a deep
+  `node_modules` tree — the reproducible offender behind the
+  intermittent hang. The Licenses report's framing notice
+  reads `typescript: stalled at >720s (deadline)` so the
+  customer sees what to act on.
+
+The class is now closed by construction: a never-settling
+provider can no longer keep `Promise.allSettled` pending
+forever; the worst-case behaviour is one capability surfacing
+as unavailable with the deadline reason visible to the user.
+
+#### Orchestrator date snapshot survives UTC-midnight rollover (D140)
+
+Long `vyuh-dxkit report` runs that crossed UTC midnight
+produced false failures. Files written before midnight got the
+old date suffix; files written after got the new one; the
+orchestrator's post-step file-existence check compared against
+the date snapshot it captured at startup. Several reports were
+on disk under the new date but the orchestrator reported them
+as missing.
+
+Fix (commit `cc1f146`):
+
+- New `src/analyzers/tools/report-date.ts` exposes
+  `getReportDate()`, which honors the optional
+  `DXKIT_REPORT_DATE=YYYY-MM-DD` env var (validated) and falls
+  back to today's UTC date.
+- The orchestrator captures the date once at startup and
+  threads it to every child subcommand via the env var, so
+  every report filename in a single run shares the same date.
+- All 10 internal date-stamping call sites in
+  `src/cli.ts` + dashboard + dev-report routed through the
+  helper.
+- 6 new tests in `test/report-date.test.ts`, including a
+  `Date.now` jump that emulates the orchestrator-snapshot
+  surviving a midnight rollover.
+
+#### Tools-used footer reads cleanly when one pack's lint skipped (D138 follow-up)
+
+The 2.4.7 D138 work landed honesty-prose in the dedicated
+`⚠ Lint coverage gap` row when one active language pack's
+linter didn't run. But the `Tools used:` footer at the bottom
+of every report was still rendering the augmented label
+verbatim — so on a polyglot repo it read
+`..., ruff (not run: typescript — config error), ...`, which
+parses as "ruff did not run because of typescript" (false;
+ruff ran fine on Python files; the parenthetical describes
+eslint's fate, not ruff's). Internal commas inside the
+parenthetical also broke the comma-split that fanned the
+footer string into individual tool names.
+
+Fix (commit `98ea153`):
+
+- New `src/analyzers/tools/lint-label.ts` centralises the
+  parse (regex + `stripNotRunSuffix` helper).
+- `splitToolNames` in `health.ts` and the `toolsUsed` push in
+  `quality/index.ts` both strip the `(not run: ...)` suffix
+  before emitting into the footer.
+- The dedicated `⚠ Lint coverage gap` row keeps its own
+  augmented-label parse — that row is exactly where the
+  per-pack skip belongs.
+- 11 tests in `test/lint-label.test.ts` cover single-pack,
+  multi-pack with internal commas, and malformed input.
+
+#### Cascade warning when health fails before the analysis cache builds (related to D141)
+
+When the Health step fails before the cross-process
+`AnalysisResult` cache is built, every downstream report
+(Vulnerabilities, BoM, Licenses, Test gaps, Quality,
+Developer) re-runs detection + Layer 0 + Layer 2 gather from
+scratch — measurably slower than the cache-hit path. On a
+heavy polyglot repo this can add hundreds of seconds across
+the run. The structural fix (build the cache from the
+gather output even when the markdown write fails) is the
+larger piece; this release surfaces the symptom honestly so
+the user understands why the remaining steps feel slower.
+
+Fix (commit `fa019f8`):
+
+- When Health fails before the cache is built, the
+  orchestrator logs:
+  `Health failed before the analysis cache could be built.
+  The remaining steps will re-detect the stack and re-gather
+  shared metrics from scratch (expect each to be measurably
+  slower than usual).`
+- No new tests — the warning is exercised end-to-end via
+  the orchestrator's existing integration coverage.
+
+#### README upgrade advisory now matches the observed behavior of modern npm (related to F3 audit finding)
+
+The 2.4.7 README's "Already installed dxkit globally?" callout
+claimed `npx @vyuhlabs/dxkit@<version>` falls through to a
+stale `vyuh-dxkit` global on PATH. Tested under npm 11.6.0
+with a stale 2.4.2 global installed, `npx @vyuhlabs/dxkit@2.4.7
+--version` correctly returned `2.4.7` — modern npm/npx does
+not fall through. A reader following the advisory might
+uninstall a working global install on advice that doesn't
+match their environment.
+
+Fix (commit `6d8363b`): rewrites the callout to keep the
+genuinely useful upgrade hint (globals don't auto-update;
+either upgrade them or remove them and rely on `npx`) without
+the inaccurate npx-behaviour assertion. Also drops the
+2.4.7-specific fix-mention which would have gone stale after
+this release.
+
+### Test posture
+
+- `npm run test:run` — **1265 / 0** (up from 1241).
+- `+6` tests for D140 (`test/report-date.test.ts`).
+- `+11` tests for D138 follow-up (`test/lint-label.test.ts`).
+- `+7` tests for D141 (`test/dispatcher-deadline.test.ts`),
+  including the D138-class regression that simulates a
+  never-settling provider and asserts the dispatcher returns
+  within the deadline window with the stalled source in
+  `skipped` + `skipReasons`.
+- arch / slop / lint / format / typecheck — all clean.
+
 ## [2.4.7] - 2026-05-17
 
 ### Summary
@@ -204,7 +630,7 @@ Fix (commit `425d0ef`):
 | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------- |
 | D124 / D100 / D118   | Vendored-source exclusion class-fix — top-largest-file metric on all 3 customer repos now first-party (or correctly flagged by the per-file advisor). Generic `largest_files` walk routes through canonical exclusions. | `72ec70a`      |
 | D113 / D128          | Per-pack lint-skip reasons plumbed end-to-end. Tools row reads `ruff (not run: typescript — config error)` instead of dropping the skip silently.                                                                       | `b878553`      |
-| D118-residue         | Graphify enumeration honors file-glob + content-minified exclusions. Webpack-hash bundles no longer rank as the densest file on customer reports (web-client: 4 606 fn artifact → 228 fn real first-party densest).     | `0da08bd`      |
+| D118-residue         | Graphify enumeration honors file-glob + content-minified exclusions. Webpack-hash bundles no longer rank as the densest file on customer reports (the JS-heavy customer frontend: 4 606 fn artifact → 228 fn real first-party densest).     | `0da08bd`      |
 | D135 / D136 (interim) | Vendored-advisor token list extended for SAP B1 OData proxy classes, map-library, proto-gen conventions. Customers with heavy-autogen .NET ERP integrations now see actionable `.dxkit-ignore` guidance.                | `d9f0c31`      |
 
 Tests at this phase close: 1241 / 0 (+15 new unit tests for
@@ -283,11 +709,11 @@ consumer.
 - **platform** (TS / Node backend): test-gap MEDIUM 207;
   Maintainability prose reads "controllers / components"
   (typescript wins cloc weight on a 106k-line monorepo).
-- **web-client** (React frontend): test-gap MEDIUM 499 → 379
+- **the JS-heavy customer frontend** (React frontend): test-gap MEDIUM 499 → 379
   (-120) because the vendored-exclusion class-fix in the
   audit-residue phase above also excludes lexical-playground
   subtrees from primary-component matching. Honest count.
-- **dpl-studio** (.NET WinForms): Maintainability vocabulary
+- **the .NET WinForms benchmark** (.NET WinForms): Maintainability vocabulary
   reads "Forms / Services"; test-gap classification correctly
   picks up the WinForms project structure.
 
@@ -401,11 +827,11 @@ for JSON-consumer migration.
 
 Two-phase release. **Phase A** (audit-driven hot-patches, originally
 shipped 2026-05-13) closed a 17-defect cascade surfaced by a critical
-post-shipment audit on dpl-studio (enterprise C# / 1500+ files / 68
+post-shipment audit on the .NET WinForms benchmark (enterprise C# / 1500+ files / 68
 sub-projects / 1.6M lines of cloc-counted JSON), plus the long-deferred
 D021 (coverage workflow). **Phase B** (class-fix release, 2026-05-14)
 pivoted from patch shipping to architectural class-fix shipping after
-pre-ship audits on platform and web-client surfaced 12 NEW defects
+pre-ship audits on platform and the JS-heavy customer frontend surfaced 12 NEW defects
 (D074–D085), 9 of which were repeated instances of the same disease
 class fixed at different sites.
 
@@ -430,7 +856,7 @@ scoring-credibility, and prioritization gaps that remained.
   siblings of `findings`; renderer reads them by name.
 
 - **C2.2 / D098 — `SECRETS_PRESENT_CAP = 40`** (commit `243fa86`).
-  Pre-C2 baseline: web-client scored Security 60/100 "Good" despite
+  Pre-C2 baseline: the JS-heavy customer frontend scored Security 60/100 "Good" despite
   4 hardcoded API keys + 1 .env in git. Credentials in source-control
   history are presumed compromised even after rotation, and a "Good"
   score reads as deprioritizable. C2.2 caps the Security dimension at
@@ -438,8 +864,8 @@ scoring-credibility, and prioritization gaps that remained.
   privateKeyFiles > 0 || envFilesInGit > 0`. Applied as a ceiling
   AFTER all per-signal penalties and the dep-availability cap, so
   it composes monotonically with everything else.
-  - Validated: web-client 60 → 40 "Fair" (✓ cap fires);
-    platform 45 → 40 "Fair" (✓); dpl-studio 90 → 90 (✓ cap
+  - Validated: the JS-heavy customer frontend 60 → 40 "Fair" (✓ cap fires);
+    platform 45 → 40 "Fair" (✓); the .NET WinForms benchmark 90 → 90 (✓ cap
     correctly does NOT fire — no committed credentials).
 
 - **C2.3 / D099 — `.env`-in-git callout block** (commit `7f43dfc`).
@@ -466,7 +892,7 @@ scoring-credibility, and prioritization gaps that remained.
   sections below.
 
 - **D108 — Top 5 sparse-tier fallback** (commit `c09ba87`). C2.5
-  audit surfaced D108: dpl-studio's Top 5 had only 1 entry despite
+  audit surfaced D108: the .NET WinForms benchmark's Top 5 had only 1 entry despite
   2 unpatched dep vulns (MongoDB.Driver risk 19 + SharpCompress
   risk 15). The original C2.4 dep filter required `riskScore >= 25`
   which excluded the "watch" tier (10-25 per risk-score.ts), leaving
@@ -478,13 +904,13 @@ scoring-credibility, and prioritization gaps that remained.
 ### Phase C2 — Verification audit (C2.5)
 
 Cross-report parity audit on three customer repos (`platform`,
-`dpl-studio`, `web-client`). All vuln-scan + health pairs verified:
+the .NET WinForms benchmark, the JS-heavy customer frontend). All vuln-scan + health pairs verified:
 
 - **D086 / D087 / D091 closures from C1 remain intact** across
   all 3 repos. Cross-report parity holds.
-- **D098 secrets-cap fires correctly**: web-client + platform both
-  drop to 40 "Fair"; dpl-studio (no secrets) stays at 90.
-- **D099 .env callout renders correctly on web-client** (the only
+- **D098 secrets-cap fires correctly**: the JS-heavy customer frontend + platform both
+  drop to 40 "Fair"; the .NET WinForms benchmark (no secrets) stays at 90.
+- **D099 .env callout renders correctly on the JS-heavy customer frontend** (the only
   repo with a tracked .env).
 - **D105 Top 5 surfaces actionable rows on every repo**, post-D108
   including the sparse-repo case.
@@ -545,7 +971,7 @@ pre-release audit and fixed before ship.
     ScoreInput fixtures predating the aggregator field).
 
 - **D107 — BoM vs vuln-scan disagreement (NEW, surfaced in C1.7
-  audit)** (commit `4ae69ed`). dpl-studio: vuln-scan reported 2 dep
+  audit)** (commit `4ae69ed`). the .NET WinForms benchmark: vuln-scan reported 2 dep
   advisories (MongoDB.Driver HIGH + SharpCompress MEDIUM via
   osv-scanner-nuget-direct) while BoM reported 0. Root cause: BoM
   walks per-sub-root project directories and called `gatherDepVulns`
@@ -555,7 +981,7 @@ pre-release audit and fixed before ship.
   now gathers dep-vulns ONCE at the repo root and passes the result
   to every per-sub-root entry builder via a new `depVulnsOverride`
   option. License-side stays per-sub-root (legitimately
-  per-project). Post-fix: dpl-studio BoM 2 ≡ vuln-scan 2.
+  per-project). Post-fix: the .NET WinForms benchmark BoM 2 ≡ vuln-scan 2.
 
 - **G_v4_9 — csharp pack cwd-invariant** (commit `14b02a7`). The
   pack-contract defect underneath D107: `gatherCsharpDepVulnsResult`
@@ -570,7 +996,7 @@ pre-release audit and fixed before ship.
   consistency.
 
 - **D091 boundary case (NEW, surfaced in C1.7 audit)** (commit
-  `c7b72e2`). Web-client `DBConfigureForm.js:43` (semgrep MEDIUM
+  `c7b72e2`). The JS-heavy customer frontend `SetupConfigForm.js:43` (semgrep MEDIUM
   `bypass-tls-verification`) and `:45` (registry HIGH
   `tls-validation-disabled`) — same root, 2 lines apart, same
   canonical rule — failed to collapse because the
@@ -579,7 +1005,7 @@ pre-release audit and fixed before ship.
   edge case in the C1.1 commit; biting in production was the trigger
   to fix it. Fix: after the natural-bucket lookup misses, check
   neighbor buckets at `(canonicalRule, file, line ± 3)`. Two
-  MEDIUMs absorbed into HIGHs on web-client, reducing apparent
+  MEDIUMs absorbed into HIGHs on the JS-heavy customer frontend, reducing apparent
   code-finding count from 13 → 11 in the right direction.
 
 - **G_v4_8 architectural gate** (commit `6e89131`) in
@@ -620,12 +1046,12 @@ post-Phase-C1):
     **81**" ≡ BoM `totalAdvisories` **81** ✓
   - 5 cross-tool TLS-bypass collisions deduped (MEDIUM bucket
     14 → 9)
-- **dpl-studio** (C#, 3 nested project roots):
+- **the .NET WinForms benchmark** (C#, 3 nested project roots):
   - vuln-scan **2** ≡ BoM **2** ≡ health **2** (dep) ✓
   - health code findings **1** ≡ vuln-scan code findings **1** ✓
-- **web-client** (JS-heavy, large repo with degraded license info):
+- **the JS-heavy customer frontend** (JS-heavy, large repo with degraded license info):
   - dep advisories **31** ≡ **31** ≡ **31** ✓
-  - D091-boundary case on `DBConfigureForm.js:43+:45` collapses (the
+  - D091-boundary case on `SetupConfigForm.js:43+:45` collapses (the
     C1.10 fix)
   - 2 MEDIUMs absorbed into HIGHs via neighbor-bucket lookup
 
@@ -657,7 +1083,7 @@ and a permanent gate:
 
 - **G_v4_7 — `walkSourceFiles` + `countLineMatches`** (new canonical
   helpers in `src/analyzers/tools/walk-source-files.ts`). Pure JS,
-  no shell. The web-client D082/D083 silent-zero cascade was caused
+  no shell. The the JS-heavy customer frontend D082/D083 silent-zero cascade was caused
   by `grep -rEf <pat> --include=*.js .` producing 67MB of stdout on
   minified files, overflowing `run()`'s 64MB ceiling, and returning
   empty. The walker prunes excluded files at the directory boundary,
@@ -699,10 +1125,10 @@ and a permanent gate:
 | D078 — BoM Risk `**0.0**` for missing CVSS | MED | `46b0d6e` (`computeRiskScore` returns `null` for `cvssScore=0`) |
 | D079 — duplicate grep-count implementations | MED | `82e0e75` + `e7a8821` (shared `gatherDebugStatements`) |
 | D080 — lint dispatcher last-wins | MED | `72cd102` (`gatherWithProvenance` exposes attempted+skipped sources; label reads `"ruff (not run: typescript)"`) |
-| D082 — web-client `consoleLogCount = 0` silent zero | CRITICAL | `0e71683` + `3275e1e` + `e7a8821` (walker prunes minified files at directory boundary) |
+| D082 — the JS-heavy customer frontend `consoleLogCount = 0` silent zero | CRITICAL | `0e71683` + `3275e1e` + `e7a8821` (walker prunes minified files at directory boundary) |
 | D083 — `run()` maxBuffer overflow on minified-JS | CRITICAL | `0e71683` + `3275e1e` + `099e844` + `32574e0` |
 | D084 — D082 cascade (anyType, eval) | HIGH | closes with D082/D083 |
-| D085 — web-client dep-count drift | HIGH | `06b0cec` |
+| D085 — the JS-heavy customer frontend dep-count drift | HIGH | `06b0cec` |
 
 **Deferred to 2.4.8**:
 - D081 (`Dead Imports: 0` suspicious) — investigated; root cause is
@@ -719,7 +1145,7 @@ and a permanent gate:
 
 Convergence audit on three customer repos:
 
-- **dpl-studio**: 1537 source files consistent across health,
+- **the .NET WinForms benchmark**: 1537 source files consistent across health,
   test-gaps, maintainability dimension; `consoleLogCount=1`,
   `tlsDisabledCount=1` stable.
 - **platform** (the audit's most-troubled repo): `sourceFiles`
@@ -727,7 +1153,7 @@ Convergence audit on three customer repos:
   `consoleLogCount` cross-report converged 1578/1555 → **698 / 698**;
   `tlsDisabledCount` 18 reported / 11 active → **11**; lint label
   `"ruff"` → `"ruff (not run: typescript)"`.
-- **web-client**: `consoleLogCount` **0 → 1066** (D082/D083 closure;
+- **the JS-heavy customer frontend**: `consoleLogCount` **0 → 1066** (D082/D083 closure;
   catastrophic silent zero eliminated).
 
 ### Phase A — Audit-driven hot-patches (2026-05-13)
@@ -792,7 +1218,7 @@ Four pieces shipped together:
   declares the names cloc emits in its `--json` output. cloc's
   per-language summary + `totalLines` aggregation now filter to the
   active-pack set, so markup/data formats (JSON / XML / CSV /
-  Markdown) stop deflating quality metrics. On dpl-studio: Comment
+  Markdown) stop deflating quality metrics. On the .NET WinForms benchmark: Comment
   Ratio 4.3% → 27.9% (a 1.6M JSON denominator vs C#'s 568K).
 
 ### Fixed — Tier 1 (credibility critical)
@@ -800,8 +1226,8 @@ Four pieces shipped together:
 The post-shipment audit's master bug + its direct cascade:
 
 - **D055** — `.dxkit-ignore` multi-segment paths flatten to basenames
-  in cloc / graphify / grep. `Dev/Addons/DPLAddon/SAPB1/` silently
-  became `{Dev, Addons, DPLAddon, SAPB1}` — cloc then excluded every
+  in cloc / graphify / grep. `Dev/Addons/VendorAddon/SAPB1/` silently
+  became `{Dev, Addons, VendorAddon, SAPB1}` — cloc then excluded every
   directory named `Dev` in the tree, killing 90% of source visibility.
   Fix: `getClocExcludeFlags` emits `--exclude-dir` (basenames) PLUS
   `--fullpath --not-match-d` (Perl regex on full path).
@@ -822,7 +1248,7 @@ The post-shipment audit's master bug + its direct cascade:
   content marker) that `gatherGenericMetrics` uses for `sourceFiles`.
   Pre-D072 docCommentFiles counted designer.cs / .g.cs files in the
   numerator but not in `sourceFiles`'s denominator, producing 104%
-  docRatio on dpl-studio even after D055.
+  docRatio on the .NET WinForms benchmark even after D055.
 - **D062** closure via **G_v4_4** above.
 
 ### Fixed — Tier 2 (visible UX bugs)
@@ -832,7 +1258,7 @@ The post-shipment audit's master bug + its direct cascade:
   W10 7, W14 1, W16 6, ...` had silent gaps that implied "data
   missing" when reality was zero commits.
 - **D061** — Hot Files filters auto-generated files via the existing
-  `autogeneratedSourcePatterns` registry. Pre-fix dpl-studio's hot
+  `autogeneratedSourcePatterns` registry. Pre-fix the .NET WinForms benchmark's hot
   list included `*.Designer.cs` files (WinForms designer regeneration
   noise).
 - **D063** — BoM Risk column rendered to one decimal (`18.5`,