From d879457f897d2f56dcd396cf8c09bb873d01a981 Mon Sep 17 00:00:00 2001 From: lucaronin Date: Tue, 14 Apr 2026 10:11:05 +0200 Subject: [PATCH] =?UTF-8?q?docs:=20add=20ADR=20for=20ratcheted=20CodeScene?= =?UTF-8?q?=20thresholds=20(guard=20=E2=80=94=20from=20commit=20311dcc64)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/adr/0018-codescene-code-health-gates.md | 3 +- .../0064-ratcheted-codescene-thresholds.md | 30 +++++++++++++++++++ docs/adr/README.md | 3 +- 3 files changed, 34 insertions(+), 2 deletions(-) create mode 100644 docs/adr/0064-ratcheted-codescene-thresholds.md diff --git a/docs/adr/0018-codescene-code-health-gates.md b/docs/adr/0018-codescene-code-health-gates.md index e6338d8b..68dabb62 100644 --- a/docs/adr/0018-codescene-code-health-gates.md +++ b/docs/adr/0018-codescene-code-health-gates.md @@ -2,8 +2,9 @@ type: ADR id: "0018" title: "CodeScene code health gates in CI and git hooks" -status: active +status: superseded date: 2026-03-13 +superseded_by: "0064" --- ## Context diff --git a/docs/adr/0064-ratcheted-codescene-thresholds.md b/docs/adr/0064-ratcheted-codescene-thresholds.md new file mode 100644 index 00000000..6f63379a --- /dev/null +++ b/docs/adr/0064-ratcheted-codescene-thresholds.md @@ -0,0 +1,30 @@ +--- +type: ADR +id: "0064" +title: "Ratcheted CodeScene thresholds as the quality gate baseline" +status: active +date: 2026-04-14 +--- + +## Context + +ADR-0018 established CodeScene code-health gates so Tolaria could block regressions before code reached `main`. Since then, the codebase has improved materially and the tracked baseline in `.codescene-thresholds` has been ratcheted above the original 9.50 / 9.31 minimums. + +Leaving ADR-0018 active would make the architecture record stale: the enforced thresholds are now stricter than the decision document says, and the current workflow intentionally tightens them as the project's sustained health improves. + +## Decision + +**Supersede ADR-0018 and treat `.codescene-thresholds` as the ratcheted policy baseline for Tolaria's CodeScene gate.** The current required minimums are `HOTSPOT_THRESHOLD=9.84` and `AVERAGE_THRESHOLD=9.45`. Thresholds move upward only when the repository can sustain a stricter baseline without immediately regressing. + +## Options considered + +- **Ratchet the enforced thresholds and document the new baseline** (chosen): keeps the ADRs aligned with the real gate, preserves the Boy Scout Rule, and makes code-health expectations stricter as the codebase improves. +- **Keep ADR-0018 active and treat higher thresholds as an implementation detail**: lower documentation churn, but the active ADR would no longer describe the actual CI and hook policy. +- **Remove numeric thresholds from ADRs entirely**: more durable on paper, but loses the explicit quality bar that developers are expected to maintain. + +## Consequences + +- `.codescene-thresholds` is now the authoritative location for the current numeric gate values. +- ADRs must be superseded again if Tolaria makes another meaningful policy jump in CodeScene thresholds. +- Pre-push and related quality checks now enforce a stricter floor than ADR-0018 described. +- The quality gate remains intentionally one-way: relaxing thresholds would require an explicit architectural reversal, not a quiet config edit. diff --git a/docs/adr/README.md b/docs/adr/README.md index 417ac732..86d74cc8 100644 --- a/docs/adr/README.md +++ b/docs/adr/README.md @@ -73,7 +73,7 @@ proposed → active → superseded | [0015](0015-auto-save-with-debounce.md) | Auto-save with 500ms debounce | active | | [0016](0016-sentry-posthog-telemetry.md) | Sentry + PostHog telemetry with consent | active | | [0017](canary-release-channel-and-local-feature-flags.md) | Canary release channel and feature flags | superseded → [0057](0057-alpha-stable-release-channels-and-beta-cohorts.md) | -| [0018](0018-codescene-code-health-gates.md) | CodeScene code health gates in CI | active | +| [0018](0018-codescene-code-health-gates.md) | CodeScene code health gates in CI | superseded → [0064](0064-ratcheted-codescene-thresholds.md) | | [0019](0019-github-device-flow-oauth.md) | GitHub device flow OAuth for vault sync | superseded → [0056](0056-system-git-cli-auth-no-provider-oauth.md) | | [0020](0020-keyboard-first-design.md) | Keyboard-first design principle | active | | [0021](0021-push-to-main-workflow.md) | Push directly to main (no PRs) | active | @@ -119,3 +119,4 @@ proposed → active → superseded | [0061](0061-ai-prompt-bridge-event-bus.md) | AI prompt bridge — module-level event bus for cross-component prompt routing | active | | [0062](0062-selectable-cli-ai-agents.md) | Selectable CLI AI agents with a shared panel architecture | active | | [0063](0063-blocknote-code-block-package-for-editor-highlighting.md) | BlockNote code-block package for editor syntax highlighting | active | +| [0064](0064-ratcheted-codescene-thresholds.md) | Ratcheted CodeScene thresholds as the quality gate baseline | active |