Skip to content

CLAUDE.md

Latest commit

 

History

History
88 lines (74 loc) · 4.51 KB

CLAUDE.md

File metadata and controls

88 lines (74 loc) · 4.51 KB
Raw

Notes for coding agents

The rule that outranks everything else

Never invent a specification, a field, a code set, or a rule citation.

This repository's entire value is that every finding cites published text. A rule citing a source you fabricated would be worse than no tool at all. If you cannot find an authoritative published source, either register the rule with implemented=False and a stated reason, or leave it out and note it in the README. Never guess.

Scope

  • Validates CEC QFER Consumption CSV filings, filer-side, before submission.
  • Five profiles: CEC-1306A-S1, CEC-1306A-S2, CEC-1306B, CEC-1308B-S1, CEC-1308C.
  • CEC-1304 is out of scope. Its instructions say reports "can be submitted by email or U.S. mail", its form is a spreadsheet, and it has no published CSV template. CEC-1306A Schedule 3 and CEC-1308B Schedule 2 are out for the same reason: SFTP channel, templates only on request.
  • Three published sources are cited: the instruction PDFs, the CSV templates, and the June 24, 2025 DSP workshop deck. A rule picks one with cites=. The README's source list is longer than that on purpose. It also records documents that were read and grounded nothing, so a later reader knows the ground was covered. Being listed there does not make a document citable.

Hard guardrails

  • Offline only. No network calls at runtime, no telemetry, no accounts, no caching of input data. A code path reaching the network is a defect.
  • Never claim or imply affiliation with, endorsement by, or approval from the California Energy Commission.
  • Never write copy implying users, adopters, downloads, or production scale.
  • No em dashes or en dashes anywhere. make verify enforces it.
  • Rule identifiers are permanent. Never renumber or reuse one.
  • Never let an unevaluated rule report as passed. See ADR 0001 and tests/test_fail_closed.py, which is load-bearing.
  • Never report an error at a value some published CEC document says is valid. When two published documents disagree, report the disagreement at warning or informational severity instead of picking a side. See ADR 0003 and ADR 0005.
  • Never let a report be silent about something the reader noticed. Anything no published rule covers goes in the advisory channel, with an ADV- code, no severity and no citation, and it keeps the verdict off pass. Advisories are not a back door for checks that could not survive as rules: the code space is closed by ADVISORY_CODES, an advisory cannot carry a severity or a citation, and the constructor refuses a message that does not say the published record fails to cover what it noticed. See ADR 0004 and tests/test_adversarial_input.py, also load-bearing.
  • Never withhold a finding without saying so. Identical findings, meaning same rule, same column, same message, merge into one line that reports its own count and example rows; nothing else merges. The one bounded listing, ten distinct findings per rule and column in the text rendering, states what it did not print and points at the JSON, which holds everything. See ADR 0006.
  • Published documents differ from each other, not only from silence. Where one form's instructions publish text another's does not, the rule applies only to the form whose text says it, and applicability is derived from the transcribed quote rather than a list of profile ids. See ADR 0007.
  • Write digit classes as [0-9], never \d. Python's \d matches every Unicode decimal digit and int() converts them, which once let a fullwidth Month through with no finding.

Build entrypoint

uv sync
make verify

make verify is the same set CI runs: format check, lint, type check, bandit, tests with the coverage floor, and the dash check.

Layout

  • src/qfer_preflight/codes.py published code sets, each with its provenance
  • src/qfer_preflight/profiles.py form templates and exact header rows
  • src/qfer_preflight/rules.py the rule registry with citations and quotes
  • src/qfer_preflight/engine.py execution and the fail-closed gating
  • src/qfer_preflight/describe.py rendering values and header rows in words, so a message names what the eye cannot see. It decides nothing.
  • src/qfer_preflight/model.py citation, rule, finding, advisory and report types
  • docs/adr/ decisions, including the fail-closed contract

Transcription convention

Published artifacts are copied exactly, defects included. Two published header typos (NumberofCustomers, RetailRatClass) are reproduced deliberately. Do not "fix" them. See ADR 0002.