Step 1.2 · done   ↑ Step 1 — Labeling (parent)  ·  → Step 2 — Coverage (next)

Permit classification & taxonomy

The two-axis permit_scope classifier (v5.3.3) — how every building permit is labelled WHAT it touches and WHAT is being done to it.

Every building permit we ingest is passed through one classifier that emits a single, MECE classification column: permit_scope. The v4 classifier emitted one value from a flat 25-entry enum that quietly mixed two unrelated questions — WHAT the permit touches (roof, pool, HVAC) and WHAT action is taken (new, replace, demolish). Five of the 25 "types" were actions wearing a type costume: a permit to "demolish a detached garage" forced the cascade to pick either DEMOLITION or GARAGE and threw the other half away. v5 splits the question into two orthogonal axes — an object axis (permit_type) and an action axis (permit_action) — so the two halves are never lost. The two axes are emitted paired inside one struct, and that paired list is permit_scope.

The two axes

Each permit_scope item is a {type, action} struct: what the permit touches drawn from a 20-value object axis, paired with what is done to it drawn from a 7-value action axis. Both axes are MECE and both are evaluated by a specificity-descending cascade — the most specific category that matches wins, the catch-alls come last.

Signal-tier scoring

Greedy substring matching was the root cause of every precision bug in both QA audits, so the classifier weights a keyword by where it appears. A field's provenance sets its tier and its score. A type joins permit_scope when its accumulated signal score ≥ 3, or when it is the primary classification.

Scoring must satisfy: TYPE/SUBTYPE > DESCRIPTION compound > PROJECT_TYPE token > generic fallback. Location-prone types (GARAGE, SHED, DECK) fire only on a Tier-1 match or a strong Tier-2 compound — never on a bare "garage" mention in DESCRIPTION. System types (HVAC, PLUMBING) may match broadly in Tier 2 because their keywords are unambiguous.

ROOFING — anti-false-positive guards

ROOFING is the highest-stakes type and the most error-prone, because roof is a substring of many unrelated words and a roof is the location of much non-roofing work. ROOFING therefore uses compound-first keywords (re-roof, roof replacement, shingle, metal roofing, tile roof, tpo, built-up roof) and is blocked by anti-FP guards unless a genuine-reroof compound fires the STRONG_ROOF rescue.

Boilerplate stripping v5.3.2

Some jurisdictions append a long standard inspection checklist to every permit DESCRIPTION ("separate permits are required for electrical, plumbing, heating…", "footing and foundation inspection", "Gopher State One Call prior to digging"). That boilerplate names every trade by design, so the classifier scored it and stuffed the scope with phantom items that were never the permit's actual work. v5.3.2 truncates DESCRIPTION before the earliest of 8 boilerplate markers (BOILERPLATE_MARKERS) — only the real work-description prefix is scored.

Output contract recap

The classifier (scripts/roofing/classify_v5.py) writes one row per Gold permit. The only taxonomy column is:

permit_scope   list<struct<type, action>>   — every (object, verb) the permit covers

type ∈ the 20 object values, action ∈ the 7 action values. The pairing is intrinsic (one struct), so type and action can never desync. permit_scope is never empty: a scopeless permit is [{OTHER, NA}] or [{UNKNOWN, NA}]. No derived columns (is_roofing, roof_action, a primary permit_type) are baked into the taxonomy — they are non-MECE projections the consumer derives:

• is_roofing = 'ROOFING' is among the permit_scope types
• roof_action = the action of the ROOFING item

Positive-eligibility rules (the label contract)

The full schema, join semantics and consumer contract live on the parent step: Step 1 — Labeling.

Audit headline numbers

Audited 2026-05-21 · v5.3.3 · 31-FIPS local layer · 98,946,381 permits

MECE check passed: 98,946,381 rows (== raw Gold), 0 empty/null scope, every type in the 20-enum and action in the 7-enum; 16.6% of rows are multi-item.

Version history

Rendered from notes/Roofing/steps/02_permit_taxonomy_v5.md + 05_labels_output_contract.md · audit notes/Roofing/audits/2026-05-21_v5.3.3_classifier_audit.md · classifier scripts/roofing/classify_v5.py (v5.3.3). This page is Step 1.2 of the roofing pipeline.