Formalize fault-ID bands; move SYS-FC-100/101 to SYS-FC-058/059; band-grouped sidebar (#38)

The numbering bands (001-049 reference-derived, 050-099 expansion,
100-149 advanced statistical, 150-199 ML) existed as one undocumented
SCHEMA line; this makes them a stated contract. SYS-FC-100/101
(flatline/spike) are deterministic rules that landed in the
advanced-statistical band — renamed to SYS-FC-058/059 with all
cross-references swept (clusters, sensor-drift playbook, sibling sys
cards). The CXF does not embed the fault ID, so content_id is unchanged
and both rules re-verify green at the pin.

tools/lint/id_bands.py enforces the checkable direction (100-149 must
be method: statistical; id must match dir) in CI; 050-099 deliberately
admits any method — 13 reference-derived statistical rules live there.

The book sidebar now groups a family's rules under band separators when
it spans bands (draft chapters), and family index pages carry a band
legend linking to the Schema.

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Author: jscott3201

.github/workflows/verify.yml

@@ -28,6 +28,10 @@ jobs:
         working-directory: cxf-library
         run: python3 tools/lint/svg_fitment.py
 
+      - name: id band lint
+        working-directory: cxf-library
+        run: python3 tools/lint/id_bands.py
+
       - uses: dtolnay/rust-toolchain@stable
 
       - uses: Swatinem/rust-cache@v2

SCHEMA.md

@@ -23,9 +23,21 @@ cxf-library/
 ```
 
 Equipment family keys: `ahu`, `vav`, `rtu`, `hp`, `fcu`, `chw`, `hw`, `erv`,
-`pmp`, `vfd`, `sys`, `tower`. Fault IDs follow `{EQUIP}-FC-{NNN}` (001–049 G36-derived,
-050–099 research-backed, 100–149 advanced statistical, 150–199 ML) per the HVAC
-FDD Reference; folder name is the fault ID, uppercase.
+`pmp`, `vfd`, `sys`, `tower`. Fault IDs follow `{EQUIP}-FC-{NNN}`; the folder
+name is the fault ID, uppercase. The number encodes the rule's provenance
+band (numbering within a band is arbitrary and IDs are never reused):
+
+| Band | Meaning |
+|---|---|
+| 001–049 | Transcribed from the HVAC FDD Reference / G36-derived; IDs preserve the source's numbering. |
+| 050–099 | Library expansion — research-, standards-, or simulation-backed rules of **any** method (threshold `rule` or `statistical`). |
+| 100–149 | Advanced statistical — sequential/accumulating (e.g. CUSUM) or fleet-relative (e.g. neighbor-median) methods. `method: statistical` required (lint-enforced). |
+| 150–199 | ML-based methods (reserved). |
+
+Band placement is set at authoring time and IDs are stable identifiers —
+renames are exceptional (the CXF does not embed the fault ID, so a rename
+never churns `content_id`, but it does break external links and every
+cross-reference).
 
 ## Design stance (why the pieces split this way)
 

clusters/clusters.json

@@ -116,8 +116,8 @@
         "AHU-FC-002",
         "AHU-FC-003",
         "SYS-FC-055",
-        "SYS-FC-100",
-        "SYS-FC-101"
+        "SYS-FC-058",
+        "SYS-FC-059"
       ],
       "playbook": "sensor-drift",
       "prevalence": "~15%",

faults/sys/README.md

@@ -7,7 +7,7 @@ this chapter:
   schedule faults, fully specified in HVAC FDD Reference v1.0 ch.16
   (pdf pages 138–147). All eight are verified — this completed the
   reference's entire fully-specified fault set.
-- **Sensor-health rules** (SYS-FC-054 + SYS-FC-100/101): the library's
+- **Sensor-health rules** (SYS-FC-054 + SYS-FC-058/059): the library's
   cross-equipment sensor-integrity family per the accepted design
   (internal sensor-health design note, local-only). SYS-FC-054 is BOTH — the
   reference's own paired-sensor cross-validation card is exactly the
@@ -33,12 +33,12 @@ Point dictionary: [`points/sys.points.json`](../../points/sys.points.json).
 | SYS-FC-055 | Virtual sensor drift detection | 3 | statistical | **verified** |
 | SYS-FC-056 | Zone heating active during summer / warm weather | 3 | rule | **verified** |
 | SYS-FC-057 | Exhaust fan schedule misalignment with AHU | 3 | rule | **verified** |
-| SYS-FC-100 | Sensor flatline while equipment active | 3 | rule | **verified** |
-| SYS-FC-101 | Sensor spike / rate-of-change violation | 3 | rule | **verified** |
+| SYS-FC-058 | Sensor flatline while equipment active | 3 | rule | **verified** |
+| SYS-FC-059 | Sensor spike / rate-of-change violation | 3 | rule | **verified** |
 
 All severities/methods are re-verified against the chapter text (SYS-FC-052
 is severity 4/info per the chapter, correcting the provisional row).
-SYS-FC-100/101 are library-authored (design doc + public sources: Yang et
+SYS-FC-058/059 are library-authored (design doc + public sources: Yang et
 al. 2008, Liao et al. 2021, Dey & Dong 2016). Naming note: the sys
 dictionary's host-derived schedule boolean is `occ_scheduled`; the ahu
 dictionary spells the same concept `occ_schedule` — a known inconsistency,

faults/sys/SYS-FC-054/card.md

@@ -23,7 +23,7 @@ suppressed_by: []
 adjudicates:
   points: [sensor_value_a, sensor_value_b]
   verdict: ambiguous
-related: [SYS-FC-055, SYS-FC-100, SYS-FC-101, AHU-FC-062, RTU-FC-052]
+related: [SYS-FC-055, SYS-FC-058, SYS-FC-059, AHU-FC-062, RTU-FC-052]
 playbooks: [sensor-drift]
 operating_states: "all, within the binding's own validity window — the two sensors must be measuring the same physical quantity at the moment of comparison, which for a stream-mixing pair is true only in particular damper or mode states (host-enforced; see preconditions)"
 preconditions: "sensor_value_a and sensor_value_b are ROLE points, not canonical names: the host's instance configuration records which real point each is bound to, and that record is also what resolves this card's adjudicates target. Both must be bound to the same quantity kind in the same units — the rule subtracts two numbers and converts nothing, so a pair trended in °C against °F reads as a permanent 30-unit divergence and alarms forever. drift_threshold ships as a temperature placeholder and MUST be retuned to the binding (see Deviations); a percent-quantity pair left at the shipped 2.0 gets a band the reference never intended. The pair must genuinely see the same quantity during evaluation, which is a per-binding claim the graph cannot check: erv_oa_entering_temp against oat holds whenever both are in the outdoor air stream, but mat against rat holds only with the outdoor air damper shut and mat against oat only at full economizer, so the host must gate those bindings on damper position and exclude the minutes after a changeover exactly as AHU-FC-062 does. Delivery quality is resolved before this rule runs, not by it: a value the host held over from twenty minutes ago reads as a divergence, and the rule is right about the number it was given and wrong about the sensor. Per the design doc's normative constraint, no other card may list SYS-FC-054 in its suppresses — an equipment fault silencing the sensor rule that invalidates it is a cycle with a wrong answer at both ends."
@@ -136,7 +136,7 @@ The reference's four, in its order:
    outdoor sensor on a sunlit wall, a probe downstream of a leak, a pair split
    across a mixing plane), which is a binding correction, not a work order
 4. Sensor failure — a transmitter drifting toward a rail, on its way to the
-   flatline SYS-FC-100 will catch when it arrives
+   flatline SYS-FC-058 will catch when it arrives
 
 Every one of the four names a single sensor and this rule cannot say which of
 the two it is; the playbook's Step 3.4 settles it by taking a reference
@@ -200,7 +200,7 @@ emits nothing. The quantity is entirely cascade, which is why
   both are kept and chained, the VFD-FC-050 shape. A single 5400 s delay behaves
   identically as shipped; the chain is what lets a site keep a 30-minute drift
   window and a two-hour alarm hold, or the reverse, without re-authoring.
-- **No activity gate, deliberately.** SYS-FC-100 needs `equip_active` because a
+- **No activity gate, deliberately.** SYS-FC-058 needs `equip_active` because a
   signal that is not moving on idle equipment is not evidence of anything; a
   bias test needs no such permission, since two thermometers in the same air
   disagree when one is wrong whether or not a fan runs. What this rule does need
@@ -211,7 +211,7 @@ emits nothing. The quantity is entirely cascade, which is why
   are combinational, and so is `GreaterThreshold` at the shipped `h = 0` — it
   takes a state word only when hysteresis is enabled — so tick one compares two
   live readings and means it. `Discrete.UnitDelay`'s tick-one artifact and the
-  ban on `Reals.Derivative` belong to SYS-FC-101; this card's only state is the
+  ban on `Reals.Derivative` belong to SYS-FC-059; this card's only state is the
   two timers.
 - **`TrueDelay` asserts at exactly `T + delayTime`,** verified against the engine
   at the pin rather than assumed: with `delayOnInit` the timer is zero on the
@@ -260,7 +260,7 @@ common false positive. Real drift opens slowly and does not close; a placement
 mismatch opens and closes with the weather, the schedule, or the damper, and the
 repair is a bracket rather than a calibration.
 
-The family's three members answer different questions: SYS-FC-100 catches the
-transmitter that has stopped moving, SYS-FC-101 the one that jumps further than
+The family's three members answer different questions: SYS-FC-058 catches the
+transmitter that has stopped moving, SYS-FC-059 the one that jumps further than
 the process can, and this one the one that is quietly wrong. A sensor that trips
-this rule and later trips SYS-FC-100 has finished failing.
+this rule and later trips SYS-FC-058 has finished failing.

faults/sys/SYS-FC-055/card.md

@@ -14,15 +14,15 @@ source:
   - "HVAC FDD Reference v1.0 §16, SYS-FC-055 (pdf pp. 144-145) — the residual equation, both published thresholds, the four diagnoses, the whole impact profile, and the Koo & Yoon note"
   - "The reference's own provenance line for that card: Koo & Yoon 2022; Sun et al. 2024 (virtual sensor RMSE 0.30 °C, bias > 1 °C detected reliably)"
   - "Accepted design: internal sensor-health design note (local-only, not distributed) (§2 stance, §2.3 the adjudicates contract, §4.3 the MovingAverage ring floor, §4.4 vector strategy)"
-  - "Library precedent: SYS-FC-054 (the pair form of the same question), SYS-FC-100/101 (the role-point sensor family), AHU-FC-056 (Reals.MovingAverage at a 64-checkpoint ring), HP-FC-050 and VAV-FC-050 (host-fitted baselines consumed as ordinary points)"
+  - "Library precedent: SYS-FC-054 (the pair form of the same question), SYS-FC-058/059 (the role-point sensor family), AHU-FC-056 (Reals.MovingAverage at a 64-checkpoint ring), HP-FC-050 and VAV-FC-050 (host-fitted baselines consumed as ordinary points)"
 g36: null
 clusters: [CLU-09]
 suppresses: []
 suppressed_by: []
 adjudicates:
   points: [physical_sensor]
   verdict: invalid_while_active
-related: [SYS-FC-054, SYS-FC-100, SYS-FC-101, AHU-FC-062, RTU-FC-052]
+related: [SYS-FC-054, SYS-FC-058, SYS-FC-059, AHU-FC-062, RTU-FC-052]
 playbooks: [sensor-drift]
 operating_states: "all, within the operating envelope the virtual sensor was trained on. The graph has no gate and evaluates whenever the host publishes a prediction, so the envelope is the host's to enforce: a Ridge model fitted over a summer learning period is extrapolating in January, and its extrapolation error arrives here as a residual indistinguishable from sensor drift. Where the host cannot vouch for the prediction it should stop publishing virtual_value rather than publish a guess."
 preconditions: "physical_sensor and virtual_value are a ROLE PAIR, not canonical names: the host's instance configuration records which real point physical_sensor is bound to, and that record is what resolves this card's adjudicates target. Both thresholds are in the BOUND point's units — the reference's 1.5 and 3.0 are its temperature defaults and MUST be retuned for any other quantity kind. Four host obligations decide whether this rule means anything. (1) The model must never take the accused sensor as one of its own features: a regression that can see physical_sensor predicts it perfectly, the residual collapses to zero, and the rule goes permanently silent while reporting health. (2) The learning period must be known-good. A model trained while the sensor was already 2 K high learns the bias as truth, and the drift becomes invisible from the moment it is fitted — this rule cannot detect a fault that predates its own baseline. (3) Model health is a separate question with a separate rule: the reference's META-FC-050 (statistical model confidence degradation) is what says the Ridge fit has stopped tracking, and a host running it should read a degraded model as NO_EVAL here rather than as sensor drift. (4) Delivery quality is resolved before this rule runs, not by it — a value held over from a dead subscription reads as a residual, and the rule is right about the number it was given and wrong about the sensor (design doc §2.2). Recommended: report NO_EVAL for the first `window` after load, where both statistics are computed over a partial window; the graph will still produce a verdict there, and `bias_present_at_load` pins what that verdict looks like."
@@ -153,7 +153,7 @@ The reference's four, in its order:
    identical output with the accused transmitter in perfect health
 
 Diagnosis 4 is the residual ambiguity to weigh against `invalid_while_active`.
-The cheap discriminator is the family: run SYS-FC-054, SYS-FC-100 and SYS-FC-101
+The cheap discriminator is the family: run SYS-FC-054, SYS-FC-058 and SYS-FC-059
 on the model's *input* sensors, and a clean bill on the features turns this
 rule's finding from a suspicion into an accusation. The expensive one is a
 reference instrument, which is where the playbook ends up anyway.
@@ -244,7 +244,7 @@ emits nothing. The quantity is entirely cascade, which is why
   never means NO_EVAL — this rule has no evaluability output, because its
   evaluability question (is the model still fit?) lives outside the graph.
 - **Role points, and the thresholds are in the bound point's units.** Same
-  documented exception as SYS-FC-054 and SYS-FC-100 (SCHEMA.md points contract):
+  documented exception as SYS-FC-054 and SYS-FC-058 (SCHEMA.md points contract):
   one graph deploys against many real points, so the host's instance
   configuration records each binding. Both published thresholds are the
   reference's temperature numbers; a humidity or pressure binding left at 1.5
@@ -260,7 +260,7 @@ emits nothing. The quantity is entirely cascade, which is why
   SYS-FC-055 as a member with SYS-FC-054 as trigger, and
   `playbooks/sensor-drift.md` already names this rule in its Applies-To row and
   in step 1.2. Both files predate this card and neither needs an edit.
-- **`category: COMFORT_ENERGY` transcribed, not argued.** SYS-FC-100 departs to
+- **`category: COMFORT_ENERGY` transcribed, not argued.** SYS-FC-058 departs to
   `PROTECTIVE` on the grounds that a sensor gate delivers avoided false alarms
   rather than energy, and the argument applies word for word here; it is not
   taken because the reference publishes a profile for *this* card and it says
@@ -295,7 +295,7 @@ calibration, never before, and treat a fault that cleared without a work order
 as a retraining event to be explained.
 
 The family's members answer different questions about the same transmitter:
-SYS-FC-100 catches the sensor that has stopped moving, SYS-FC-101 the one that
+SYS-FC-058 catches the sensor that has stopped moving, SYS-FC-059 the one that
 jumps further than the process can, SYS-FC-054 the one that disagrees with a
 partner in the same air stream, and this one the one that disagrees with
 everything else at once. The

faults/sys/SYS-FC-056/card.md

@@ -179,7 +179,7 @@ should follow the actual heating source (the same caveat VAV-FC-055 carries).
 - **`oat` drift is the standing false positive and this card does not solve
   it.** A sun-baked or drifted outdoor sensor reading 3 K high manufactures the
   fault across every zone at once, which is also the tell. SYS-FC-054,
-  SYS-FC-100 and SYS-FC-101 adjudicate `oat` directly; where a host runs them,
+  SYS-FC-058 and SYS-FC-059 adjudicate `oat` directly; where a host runs them,
   an active sensor finding on the bound `oat` makes this rule NO_EVAL through
   the `adjudicates` fan-out.
 - **`clusters: [CLU-05]` is a declaration, not an edit.** CLU-05 already lists

faults/sys/SYS-FC-100/card.md faults/sys/SYS-FC-058/card.mdfaults/sys/SYS-FC-100/card.md renamed to faults/sys/SYS-FC-058/card.md

@@ -1,6 +1,6 @@
 ---
 schema: cxf-library/fault-card/v1
-id: SYS-FC-100
+id: SYS-FC-058
 name: Sensor flatline while equipment active
 equipment: sys
 status: verified
@@ -24,7 +24,7 @@ suppressed_by: []
 adjudicates:
   points: [sensor_value]
   verdict: invalid_while_active
-related: [SYS-FC-054, SYS-FC-101, AHU-FC-062, RTU-FC-052]
+related: [SYS-FC-054, SYS-FC-059, AHU-FC-062, RTU-FC-052]
 playbooks: [sensor-drift]
 operating_states: "all — the rule evaluates only while equip_active is true, and its own yWindowOk reports whether a complete window of running time has accumulated"
 preconditions: "Host delivery quality must be resolved before this rule runs, and this is the load-bearing precondition rather than boilerplate: a value the host is re-serving from cache because the subscription died presents to the graph as a perfectly frozen sensor, and the rule will report flatline and be right about the number it was given and wrong about the transmitter. Freshness, PointStatus and gap handling stay where the reference's ch.4 puts them — host-side, ahead of this rule (design doc §2.2). sensor_value must be bound to a live measurement: a setpoint, a configured constant, a schedule output or a host-derived aggregate that only refreshes hourly will all read as flatline and none of them is a sensor. equip_active must be bound to the run status of the equipment whose process actually drives the bound sensor — sf_status for an AHU supply-air temperature, comp_status for a suction line, pump_status for a loop reading. A VAV box has no run status of its own; bind the parent AHU's fan status or zone_airflow > 0 and record which. Both flatline_band and flatline_window are per-binding site configuration in the bound point's units and MUST be set for this instance before the rule is trusted; the shipped defaults are a worked example for a supply-air temperature, not a site value. Where yWindowOk is false the verdict is NO_EVAL, not a healthy sensor."
@@ -103,7 +103,7 @@ yFault     = (still AND equip_active) held continuously for flatline_window,
 
 Block graph (`rule.cxf.jsonld`):
 
-![SYS-FC-100 block graph](diagram.svg)
+![SYS-FC-058 block graph](diagram.svg)
 
 Eight blocks. `sensRef` is a `Discrete.Sampler` on the window period, so the
 comparison is always against where the reading sat at the start of the current
@@ -225,7 +225,7 @@ heating fault or an electric cooling one, and the rule does not know which.
   reporting twice the actual slope at a 300 s tick with `T = 300 s`.
 - **`Discrete.Sampler` emits the live input on its first tick,** so there is no
   startup artifact of the kind `Discrete.UnitDelay` produces with `y_start = 0`
-  (that is SYS-FC-101's problem). This is pinned by an arrival time rather than
+  (that is SYS-FC-059's problem). This is pinned by an arrival time rather than
   asserted: the alarm lands at `flatline_window + alarm_delay` from t = 0, which
   is only reachable if the first baseline was the live reading.
 - **The sampler grid is anchored to absolute model time, not to controller
@@ -244,7 +244,7 @@ heating fault or an electric cooling one, and the rule does not know which.
   `flatline_band` per `flatline_window` satisfies the test. That is a sensor
   finding either way, but the *name* is wrong and this rule cannot supply the
   right one — naming drift is SYS-FC-054's job, and a host running both should
-  read a simultaneous SYS-FC-100 and SYS-FC-054 as drift, not two faults.
+  read a simultaneous SYS-FC-058 and SYS-FC-054 as drift, not two faults.
 - **Strict `<` on the band.** CDL `Reals` has no `LessEqual` and the
   disagreement is measure-zero on a real-valued signal, so the comparison errs
   toward silence. Edge cases use dyadic values (14.0 against 14.25) so the