feat/energy-api

DynamoDB key schema '/oid/cid/sid' is wrong for prod-ddb-electricity-rates

.claude/rules/infrastructure.md

The rule claims all three DynamoDB tables are 'keyed by /oid/cid/sid'. This is factually incorrect for prod-ddb-electricity-rates, which is keyed by rate_division (hash) + year_month (range) — confirmed by packages/database/src/seed-tariff-rates-historical.ts. The /oid/cid/sid notation is the legacy siteKey path format, relevant only to prod-ddb-metrics-sites-devices. Applying it uniformly will mislead anyone trying to query or cross-account-access the rates or simulated-bills tables in Phase 9.

SIMULATED_CFE_TOTAL listed as a 'deduction type' but it is the savings baseline

.claude/rules/savings-billing.md

The new 'Deduction contract types' table lists SIMULATED_CFE_TOTAL as a deduction that prices 'the baseline no-solar counterfactual'. But savings-billing.md § The formula defines savings as 'baseline − Σdeductions', where SIMULATED_CFE_TOTAL IS the baseline (the minuend), not something subtracted. computeSavingsReportShell skips SIMULATED_CFE_TOTAL when it appears as a deduction type. Framing it as a deduction inverts its role in the savings formula and will cause confusion when adding contract types or debugging savings mismatches.

Phase-9 legacy FAC discrepancy not documented in the THOR/FAC section

.claude/rules/ontology.md

The PR body documents a known Phase-9 finding: 'legacy stores energy_adjustment=1.035 but energy_charges = kWh × energy_rate (FAC NOT applied to the charge); our calculator applies THOR FAC multiplicatively. Reconcile before host cutover.' The THOR section describes the new behavior as canonical but does not note this divergence from legacy. A developer running the Phase-9 A/B will observe a systematic ~3.5–8.5% charge delta on THOR sites and will have no rule document explaining whether it is a bug or an intentional improvement.

GDMTH THOR FAC '≈ 1.085' is period-specific, not a fixed system constant

.claude/rules/ontology.md

The rule states 'GDMTH THOR ≈ 1.085, PDBT THOR ≈ 1.035'. Seed data shows GDMTH THOR carried energyAdjustment=1.0 for Jan–Jun 2024 and several older months, with 1.085 only from Jul 2024 onwards. Without qualification, this reads as a fixed system constant. Developers back-testing historical THOR bills who see FAC=1.0 applied may incorrectly conclude the rate row is corrupt rather than period-appropriate.

Customer financial data (powen-savings.json/html) persists in branch git history

.scratch/powen-savings.json

The files are now correctly untracked and .scratch/ is gitignored — future commits are safe. However, powen-savings.json (per-site monthly energy kWh + MXN billing figures for Powen customer sites) was committed in a prior commit and remains in git history. Merging the PR as-is carries these git objects into main permanently. Remediation before merge: rewrite branch history with `git filter-repo --path .scratch/ --invert-paths` (or BFG) then force-push. This is a carry-over finding from the previous review; only the working-tree half has been addressed.

Real customer site names and peso figures used as validation anchors in savings-billing.md

.claude/rules/savings-billing.md

The file references 'Powen MC1 2026-02: gross 109,681 vs net billTotal 53,194' and names 'MC Industrias 1', 'Teknia', 'Aceros Alcalde' with exact MXN amounts as algorithm validation examples. These are real production customer names and figures. While the data is used as algorithm anchors (not a bulk dump), these values will be in every clone's git history. Consider anonymising the site labels before merge, or obtain explicit approval that this level of detail in internal rules files is company policy.

.scratch/ and .branch/ are now correctly untracked and gitignored

.gitignore

git ls-files .scratch/ and git ls-files .branch/ both return empty — no tracked files remain. .scratch/ is now on line 153 of .gitignore; .branch/ was already gitignored. Future working files in these directories will not be staged by git add. The working-tree side of this cleanup is complete.

Infrastructure note contains temporal/phase-specific task state in a permanent rule

.claude/rules/infrastructure.md

The added paragraph states 'still-open Phase-9 legacy peso-to-peso A/B (energy-api port) needs cross-account creds to read them.' CLAUDE.md is explicit: rules define how things should be built, not current task state. Once Phase-9 closes, this note becomes wrong. The durable fact (management account holds these DynamoDB tables, never deploy stacks there) is useful and should stay; the phase-reference and 'still-open' qualifier belong in the Linear issue or PR description, not a permanent rule file.

TOU and THOR sections appended after 'Deferred' section — breaks ontology.md hierarchy

.claude/rules/ontology.md

The new ## CFE TOU classification and ## THOR sections appear after '## Deferred: tariff-rate ontology rework'. The file organises content as top-level ## domain sections (Core / Utility / Metrics), then Deferred. Appending new durable sections after Deferred makes them visually appear deferred too. Both belong as ### subsections under '## Utility Domain' (both live in domains/utility/) or immediately before Metrics Domain — not trailing after the Deferred group.

Management account ID repeated — already in the account segmentation table

.claude/rules/infrastructure.md

The account ID 397762539248 already appears in the account segmentation table three lines above the new paragraph. Convention in infrastructure.md is to define the ID once in the table and use the human label ('management account') in prose. This is a minor DRY violation with trivial remediation.

Summer GDMTH 'base=0' case not tested in TOU classifier or breakdown

domains/utility/src/tou-schedule/__tests__/tou-schedule.decisions.test.ts

The rule documents a critical gotcha: summer GDMTH weekday has NO base period, so base=0 is CORRECT. No test exercises this path. All tou-schedule.decisions tests use GDMTH_BC_WINTER (which always has a base window). A regression here would silently misclassify all summer weekday slots — breaking the conservation invariant without a failing test. A test using a real summer GDMTH SIN schedule (weekday.base=[]) asserting decideTouPeriod returns non-null for all hours and base contribution sums to 0 is missing.

TOU conservation invariant tested only in cross-domain, not in the classifier's own tests

domains/utility/src/tou-schedule/__tests__/tou-schedule.decisions.test.ts

The Σ(base + intermedio + punta) == window total invariant is verified in domains/cross-domain/__tests__/site-energy-metrics-breakdown.test.ts (toBeCloseTo 1.5, 9) but not in the TOU scheduler's own unit suite. Coverage exists at the integration level; adding a unit-level invariant check inside tou-schedule.decisions.test.ts (iterating all 1440 minute-slots on a known schedule) would isolate classifier failures from transform failures.

SIMULATED_CFE_TOTAL deduction-skip guard not unit-tested

domains/cross-domain/src/__tests__/savings-cfe-grid.test.ts

savings-report-compute.shells.ts silently skips SIMULATED_CFE_TOTAL when it appears as a deduction type. No unit test asserts this skip behavior. If the guard were inadvertently removed, the baseline bill would be subtracted from itself (yielding near-zero savings) with no test failure to catch it.

Infrastructure DynamoDB note gives no path to obtain cross-account credentials

.claude/rules/infrastructure.md

The note correctly identifies that Phase-9 needs cross-account creds to read the management account DynamoDB tables, but provides no guidance on how to obtain them: no IAM role name, no SSO permission set, no runbook reference. The standard 'batu-dev' SSO profile cannot access the management account per the same file's 'never deploy stacks here' rule. A developer attempting the A/B validation is left at a dead end. At minimum: note whether a cross-account read role exists, who to ask, or a Linear issue link.

bill-compute.shells.ts cited without path qualifier — lives in cross-domain, not utility

.claude/rules/ontology.md

The THOR section references 'bill-compute.shells.ts' without a path. The file lives at domains/cross-domain/src/bill-compute.shells.ts. In the context of ontology.md (a domain entity doc), readers may look in domains/utility/src/ first. Adding the full relative path removes the ambiguity.