choiyounggi · choiyounggi · Sep 5, 2026
@@ -11,8 +11,8 @@ follow the cross-pointers in their index or take the next matching seeded domain
 
 | Domain | Status | Route here when |
 |--------|--------|-----------------|
-| [databases](wiki/databases/index.md) | **seeded** | Choosing a datastore/database type for a workload (relational vs document vs vector vs graph), designing schemas/tables/keys, choosing or evaluating indexes, writing or optimizing queries, choosing transaction/isolation behavior, surveying live data to derive a rule, verifying additive migrations |
-| [backend](wiki/backend/index.md) | **seeded** | Server-side application code — language-agnostic (`common/`: API contracts, call-site enumeration before a contract change, idempotency, JWT, timeouts/retries, caching, jobs, transactions in app code, shared state/pools, errors, consuming LLM APIs (completion validation, context budgeting), authoring agent-facing artifacts (binding instruction text, agent tool-surface granularity/parity), MAPE-aligned point-prediction calibration, consuming external-API responses, externally-owned defaults, object-storage references, sync-vs-async integration choice, WebSocket/SSE connection lifecycle) plus stack subtrees: `java/` (JPA, Spring proxies, JVM threads/memory), `node/` (event loop, promises, runtime validation, shutdown), `python/` (GIL/asyncio, pydantic, WSGI/ASGI workers, language traps, packaging data files with `importlib.resources`) |
+| [databases](wiki/databases/index.md) | **seeded** | Choosing a datastore/database type for a workload (relational vs document vs vector vs graph), designing schemas/tables/keys, choosing or evaluating indexes, writing or optimizing queries, choosing transaction/isolation behavior, multi-row rewrites (reorder, bulk status) on a shared resource, surveying live data to derive a rule, verifying additive migrations |
+| [backend](wiki/backend/index.md) | **seeded** | Server-side application code — language-agnostic (`common/`: API contracts, call-site enumeration before a contract change, idempotency, JWT, timeouts/retries, caching, jobs, transactions in app code, shared state/pools, errors, consuming LLM APIs (completion validation, context budgeting), authoring agent-facing artifacts (binding instruction text, agent tool-surface granularity/parity), MAPE-aligned point-prediction calibration, benchmark-relative signal rating, consuming external-API responses, externally-owned defaults, object-storage references, sync-vs-async integration choice, WebSocket/SSE connection lifecycle) plus stack subtrees: `java/` (JPA, Spring proxies, JVM threads/memory), `node/` (event loop, promises, runtime validation, shutdown), `python/` (GIL/asyncio, pydantic, WSGI/ASGI workers, language traps, packaging data files with `importlib.resources`) |
 | [frontend](wiki/frontend/index.md) | **seeded** | Web UI code: state placement, rendering performance, in-UI data fetching (races, infinite scroll), auth token handling, forms, XSS-safe output, accessibility, agent-facing tool surfaces (WebMCP) |
 | [infrastructure](wiki/infrastructure/index.md) | **seeded** | CI/CD pipelines, secrets in build/deploy, container image builds, rollout/rollback strategy, observability (logs/metrics/alerting), per-environment/path-valued config, multi-agent orchestration (worker liveness signals, shared run state, tmux pane delivery, completion gates, worktree-isolated workers, autonomous ask-vs-rule decisions, session context/token budgeting, a pre-built code knowledge graph as a freshness-gated orientation layer for planning) |
 | [testing](wiki/testing/index.md) | **seeded** | Writing or structuring automated tests: level choice, test-before-code ordering, cases/assertions, cross-layer effect scoping, test data, mock decisions, flaky tests (release-process quality → qa) |

@@ -104,3 +104,12 @@ Append-only. Format: `## [YYYY-MM-DD] <ingest|revise|lint|gap|contradiction|drif
 ## [2026-08-30] revise | frontend/design/design-canvas-workflow — agent-gate Check 3 remediation (PR #164). The gate's fact finding was half right: its "no skill named `design` exists" conclusion is refuted by ground truth (the skill is listed in the authoring session's available-skills roster as `design: Create a design canvas…` and its bundled payload exists on the authoring machine's disk; the reviewer's CI environment lacks the preview, and it conflated the skill with the unrelated `/design-sync` component-upload tool) — but the verifiability objection stands: the skill is an early research preview absent from public docs, so a single un-fetchable in-session source cannot carry `confidence: verified`. Fixed per AGENTS.md: confidence downgraded to field-tested with the experience context stated in the body; two live-fetched public sources added (anthropic.com/news/claude-design-anthropic-labs — official Claude Design product announcement, research preview, Claude Code handoff; explainx.ai 2026 post — /design ships in Claude Code as a research-preview command producing editable artboards via the Artifacts runtime); the mandatory-routing directive and the frontend/index.md load-when line conditioned on the skill appearing in the session's available-skills list, with the existing no-skill edge case as the explicit fallback; the unverifiable "design-review skill" name-drop in the audit edge case generalized to session-provided audit tooling.
 ## [2026-09-03] ingest | databases/selection — new category: datastore selection by workload (4 pages: choosing-a-datastore-by-workload, relational-jsonb-vs-document-store, vector-search-engine-selection, graph-workloads-relational-vs-graph-db); brave-search research, sources cited per page
 ## [2026-09-04] ingest | infrastructure/agent-orchestration/code-graph-as-orientation-layer (field-tested — 1 new page). A locally built code knowledge graph (graphify) is a freshness-gated, lead-not-evidence orientation layer for planning and parallel task decomposition: gate on graph mtime vs git log, symbol-anchored explain/path only, CLI delivery with bounded output, graph-derived assumptions named in reports. Sources: Developers Digest, AQ Score, Autonoma, Tiare Balbi, graphify README + measurements on graphifyy 0.4.23.
+## [2026-09-06] ingest | frontend-design-lightness-steps-on-dark-surfaces — OKLCH lightness steps below L 30% collapse to ~1.1–1.3:1 in sRGB; gate state cues on the measured ratio and carry identification on outline/chroma/shape
+## [2026-09-06] ingest | backend-common-ml-benchmark-relative-signal-classification — grade per-entity signals on excess return over the benchmark for the same window; a population-wide burst is a shared driver, not N signals
+## [2026-09-06] ingest | databases-transactions-multi-row-reorder-on-a-shared-resource — parent-row lock + one transaction, deferrable unique position, explicit final-state rule, two-writer test
+## [2026-09-06] ingest | databases-schema-design-online-schema-changes — Prisma Migrate's implicit transaction on multi-statement files breaks CONCURRENTLY; check the live-large-table premise before applying the rule
+## [2026-09-06] ingest | infrastructure-agent-orchestration-code-graph-as-orientation-layer — graphify update on >5,000 nodes fails only at HTML export; graph.json is already current
+## [2026-09-06] ingest | infrastructure-agent-orchestration-session-context-token-budget — measure a live session from the newest transcript file, not the project directory
+## [2026-09-06] ingest | testing-async-async-testing — rewind the fake clock to before the lock's TTL to isolate an explicit clear; mutation-check the clear
+## [2026-09-06] ingest | infrastructure-observability-alerting — alert on primary-source success count reaching zero when a fallback silently takes over
+## [2026-09-06] ingest | folds onto open PRs: #179 worktree-isolated-workers (clean-worktree-at-done recovery via git apply --3way) + semantic-conflicts-after-parallel-merge (stale install/codegen in the integration worktree); #181 checkable-claims-in-an-adopted-plan (author-side reuse-claim grep)
@@ -9,7 +9,7 @@ sources:
   - https://en.wikipedia.org/wiki/Slippage_(finance)
   - "Live incident 2026-08-13/14 (KIS auto-trading bot): 6 positions exited TAKE_PROFIT at +0.06%–+0.42% against a +2% design; re-anchor in mark_filled() restored the band, regression tests red on pre-fix code"
 last_verified: 2026-08-14
-related: []
+related: [backend-common-ml-benchmark-relative-signal-classification]
 ---
 
 # Absolute Thresholds Derived from a Pre-Execution Estimate

@@ -0,0 +1,78 @@
+---
+id: backend-common-ml-benchmark-relative-signal-classification
+domain: backend
+category: ml
+applies_to: [general]
+confidence: verified
+sources:
+  - https://corporatefinanceinstitute.com/resources/equities/abnormal-return/
+  - https://www.wallstreetprep.com/knowledge/information-ratio/
+  - "Field measurement 2026-08-26 (stock-signal-bot, KRX): a 5-day +4.44% move graded as entity-specific strength sat under the KOSPI's +5.21% over the same window"
+last_verified: 2026-09-06
+related: [backend-common-integrations-estimate-derived-thresholds, backend-common-ml-mape-aligned-point-prediction, infrastructure-observability-alerting]
+---
+
+# Rating a Per-Entity Signal While a Shared Driver Moves Every Entity
+
+## When this applies
+
+Code classifies a per-entity observation as entity-specific strength or weakness
+— a stock's price move or buy-flow (institutional + foreign net buying), a
+store's sales jump, a service's latency change, a cohort's conversion lift — and
+a driver shared by every entity in the population (the market index, a holiday,
+a platform-wide release, seasonality) moves all of them at once; deciding the
+inputs a signal grader needs before it labels anything "strong".
+
+## Do this
+
+1. **Compute the benchmark's return over the same window as the entity's, and
+   grade the difference, not the raw move.** Excess return = entity return −
+   benchmark return over identical start and end points. A signal earns
+   "entity-specific" only when the excess is positive (or beyond a floor you
+   set); a raw +0.88% day on a +0.97% index day is a −0.09% excess, a lag.
+
+| Observation | Read it as |
+|-------------|------------|
+| Entity up, excess > 0 | Entity-specific strength — grade the signal |
+| Entity up, excess ≤ 0 | Benchmark-driven; the entity lagged — grade as neutral or weak |
+| Entity flat or down, excess > 0 | Relative strength (held up while the population fell) — grade it |
+| Benchmark unavailable for the window | Withhold the grade and log the missing benchmark; a grade computed without it is the raw move relabelled |
+
+2. **Use one window for both sides and carry it in the record.** Store
+   `window_start`, `window_end`, `entity_return`, `benchmark_return`, `excess`
+   next to the grade so a reviewer can recompute; a same-day flow signal graded
+   against a 5-day price window is two different claims.
+
+3. **Treat a population-wide signal burst as a driver, not a discovery.** When
+   the same "strong" label fires on most large entities on one day, the shared
+   driver is the cause; gate the grade on excess return and on the share of the
+   population also flagged (a flag on more than a set share of the universe is a
+   market event, not that many signals).
+
+4. **Choose the benchmark by what the entity is compared against in the
+   consumer's decision** — a broad index for market-wide flow signals, a sector
+   index for sector rotation, a control cohort for product experiments — and
+   name it in the output.
+
+## Edge cases
+
+| Case | Then |
+|------|------|
+| The entity's window includes a day the benchmark did not trade (holiday, halt) | Align to the entity's trading days: take the benchmark's values on those exact dates; a calendar-day window mixes different day counts |
+| The benchmark is a composite the entity dominates (a mega-cap in a cap-weighted index) | Use an equal-weighted or ex-entity benchmark; otherwise the entity is measured against itself |
+| Only daily flow counts (buyer categories) exist, with no benchmark flow series | Grade the flow on the price excess return over the same window; flow direction alone is the population-wide signal this page warns about |
+| The consumer wants the raw move too | Emit both fields; the grade is computed from the excess, the raw move is displayed |
+
+## Instead of
+
+| If you are about to | Do this instead | Why |
+|---------------------|-----------------|-----|
+| Label "institutions and foreigners both net-bought and the stock rose" as strength | Compute the stock's excess return over the index for the window first | In an index rally nearly every large entity carries that pattern; without the benchmark the label's discrimination is near zero |
+| Compare today's move to the index but grade a multi-day trend | Align both sides to the same window before grading | A one-day beat inside a five-day lag reverses the conclusion (measured: +0.88% vs +0.97% on the day, +4.44% vs +5.21% over five days) |
+| Skip the benchmark when its feed is down | Withhold the grade and alert on the missing input | A grade emitted without its denominator is silently degraded output ([infrastructure-observability-alerting], fallback row) |
+
+## Sources
+
+- https://corporatefinanceinstitute.com/resources/equities/abnormal-return/ — "Excess Return = Actual Return − Expected Return", with the market index as the expected return in the worked example (12% − 14% = −2%)
+- https://www.wallstreetprep.com/knowledge/information-ratio/ — active performance is "the excess return over a benchmark", the standard denominator for judging entity-specific performance
+- Field measurement 2026-08-26 (stock-signal-bot, KRX): close 1,531,000 (08-18) → 1,599,000 (08-26) = +4.44% while the KOSPI 5-day return was +5.21%; the same day's +0.88% sat under the index's +0.97%; the buy-flow signal graded as strength was a lag once benchmarked, and the grader was changed to require positive excess return
@@ -5,7 +5,7 @@ three stack subtrees — route by concern first, stack second:
 
 | Subtree | Route there when |
 |---------|------------------|
-| [common](#common-language-agnostic) (below) | The concern is language-agnostic: API contracts, enumerating call sites before a contract change, idempotency, JWT issuance, outbound calls, caching, jobs, transactions in app code, shared state/pools, exception structure, consuming LLM APIs (completion validation, context budgeting), MAPE-aligned point-prediction calibration, consuming external-API responses, externally-owned defaults, object-storage references, sync-vs-async integration choice, WebSocket/SSE connection lifecycle |
+| [common](#common-language-agnostic) (below) | The concern is language-agnostic: API contracts, enumerating call sites before a contract change, idempotency, JWT issuance, outbound calls, caching, jobs, transactions in app code, shared state/pools, exception structure, consuming LLM APIs (completion validation, context budgeting), MAPE-aligned point-prediction calibration, benchmark-relative signal rating, consuming external-API responses, externally-owned defaults, object-storage references, sync-vs-async integration choice, WebSocket/SSE connection lifecycle |
 | [java](java/index.md) | You are writing/reviewing JVM backend code (Java/Kotlin, Spring, JPA/Hibernate) and the concern is stack-specific: entity mapping, persistence context, proxy pitfalls, JVM threads/memory |
 | [node](node/index.md) | You are writing/reviewing Node.js/TypeScript backend code: event-loop blocking, promise error handling, runtime validation at boundaries, graceful shutdown |
 | [python](python/index.md) | You are writing/reviewing Python backend code: GIL/concurrency model, pydantic validation, WSGI/ASGI workers, language traps, packaging data files and resolving them after install |
@@ -103,6 +103,7 @@ Match your situation to a "load when" line; load only matching pages.
 | Page | Load when |
 |------|-----------|
 | [mape-aligned-point-prediction](common/ml/mape-aligned-point-prediction.md) | A regression model evaluated by MAPE was trained as a median predictor (log target + L1 loss, or quantile q50) — deciding what point value to emit, or the model systematically overpredicts on MAPE despite fitting well; choosing between a global scale factor and per-row variance-based correction |
+| [benchmark-relative-signal-classification](common/ml/benchmark-relative-signal-classification.md) | Code grades a per-entity observation (a stock's move or buy-flow, a store's sales jump, a cohort's lift, a service's latency change) as entity-specific strength while a driver shared by the whole population (market index, holiday, platform-wide release, seasonality) moves every entity; the same "strong" label fires across most of the population on one day; choosing the benchmark and the window a signal grader needs; the benchmark feed is missing |
 
 ### integrations
 

@@ -83,3 +83,4 @@ Match your situation to a "load when" line; load only matching pages.
 | [isolation-level-selection](transactions/isolation-level-selection.md) | Check-then-act writes, lost updates, duplicate bookings, choosing isolation/locking; deadlock-detected errors; oversell despite @Transactional |
 | [optimistic-vs-pessimistic-locking](transactions/optimistic-vs-pessimistic-locking.md) | Multi-step read-modify-write that cannot fold into one UPDATE — choosing version-column optimistic vs FOR UPDATE by conflict frequency; stale form submits; retry storms on hot rows |
 | [application-clock-vs-database-timestamps](transactions/application-clock-vs-database-timestamps.md) | A predicate compares an application-produced timestamp against a DB-filled column (`created_on > $boundary`, "older than N minutes"); one step classifies rows by a time boundary and a later step cancels/deletes what it chose; choosing between `RETURNING` the DB clock and adding a skew margin; deciding whether timestamp order can stand in for commit order |
+| [multi-row-reorder-on-a-shared-resource](transactions/multi-row-reorder-on-a-shared-resource.md) | Designing or reviewing an action that rewrites many rows of one parent at once (drag-to-reorder positions, bulk status change, re-ranking) on a resource several clients edit; a `unique (parent_id, position)` constraint exists or is proposed and the rewrite fails mid-way; deciding the transaction boundary, the constraint's deferral, and the final-state rule when two reorders race; writing the two-writer test |