clearancewatch 0.1.0__tar.gz

clearancewatch-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 calasdan-sketch
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

clearancewatch-0.1.0/PKG-INFO

@@ -0,0 +1,99 @@
+Metadata-Version: 2.4
+Name: clearancewatch
+Version: 0.1.0
+Summary: Track subcontractor compliance per job: WSIB/WCB clearance coverage, insurance and licence expiry against the job calendar
+Author: calasdan-sketch
+License-Expression: MIT
+Keywords: wsib,wcb,clearance,compliance,construction,trades,insurance
+Classifier: Programming Language :: Python :: 3
+Classifier: Environment :: Console
+Classifier: Topic :: Office/Business
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# clearancewatch
+
+**A principal must hold valid workers'-comp coverage for every sub — for the whole job.** `clearancewatch` audits subcontractor compliance documents against the job calendar and tells you what's expired, what expires mid-job, and what's coming up for renewal.
+
+Rules modelled from official sources (verified October 2026):
+
+- **Ontario WSIB**: clearance certificates are valid **up to 90 days**; WSIB states a principal must ensure a valid clearance is in place for the **full length of a job**. ([wsib.ca clearances](https://www.wsib.ca/en/businesses/premiums-and-payment/clearances))
+- **Alberta WCB**: a clearance letter is valid for work done **up to the date of the letter** — WCB advises requesting one at hire and before each installment. ([wcb.ab.ca clearance letters](https://www.wcb.ab.ca/insurance-and-premiums/clearance-letters/))
+
+> **This is not legal advice.** It's a date-tracking assistant built on the rules above; confirm obligations with your broker, WSIB/WCB, or counsel.
+
+## Install
+
+```bash
+pip install clearancewatch
+```
+
+## Jobs file
+
+```json
+[
+  {
+    "name": "Kitchen reno",
+    "province": "ON",
+    "start": "2026-02-01",
+    "end": "2026-03-30",
+    "subs": [
+      {
+        "name": "Bob's Drywall",
+        "trade": "drywall",
+        "clearance": { "issuer": "WSIB", "number": "1234567", "issued": "2026-01-10", "expires": "2026-04-10" },
+        "insurance": { "provider": "Aviva", "policy": "GL-9", "coverage": "C$2M", "expires": "2026-12-31" },
+        "licences": [ { "name": "Fall protection", "expires": "2026-09-01" } ]
+      }
+    ]
+  }
+]
+```
+
+## Usage
+
+```bash
+clearancewatch audit jobs.json --on 2026-02-15 --within 30
+clearancewatch renewals jobs.json --within 30     # just what's coming due
+clearancewatch audit jobs.json --json             # machine-readable
+```
+
+```
+ERROR clearance_expires_during_job  Kitchen reno / Bob's Drywall: clearance expires 2026-03-15 before job end 2026-03-30...
+WARN  renewal_due                   Kitchen reno / Bob's Drywall: insurance expires 2026-03-05 (within 30 days)
+
+1 error(s), 1 warning(s) — FAIL
+```
+
+Exit `1` when any error-severity finding exists (missing/expired clearance, lapsed coverage, expired insurance or licence) — CI- and cron-friendly.
+
+## What it catches
+
+| Finding | Severity |
+|---|---|
+| `clearance_missing` / `clearance_expired` / `clearance_expires_during_job` | error |
+| `clearance_cover_lapsed` (Alberta letter predates ongoing work) | warn |
+| `issuer_mismatch` (ON job, WCB-AB clearance — or vice versa) | warn |
+| `insurance_missing` / `insurance_expired` | error |
+| `insurance_expires_during_job` | warn |
+| `licence_expired` | error |
+| `renewal_due` / `insurance_renewal_due` / `licence_renewal_due` (within `--within` days) | warn |
+
+## Python API
+
+```python
+import datetime as dt
+from clearancewatch import Job, audit
+
+job = Job.from_dict({...})
+for finding in audit(job, on=dt.date(2026, 2, 15), horizon=30):
+    print(finding.severity, finding.code, finding.detail)
+```
+
+`clearancewatch renewals` over a weekly cron gives you the "call these three subs" list before a gap becomes a deeming problem.
+
+## License
+
+MIT-style: use it, ship it, no warranty.

clearancewatch-0.1.0/README.md

@@ -0,0 +1,84 @@
+# clearancewatch
+
+**A principal must hold valid workers'-comp coverage for every sub — for the whole job.** `clearancewatch` audits subcontractor compliance documents against the job calendar and tells you what's expired, what expires mid-job, and what's coming up for renewal.
+
+Rules modelled from official sources (verified October 2026):
+
+- **Ontario WSIB**: clearance certificates are valid **up to 90 days**; WSIB states a principal must ensure a valid clearance is in place for the **full length of a job**. ([wsib.ca clearances](https://www.wsib.ca/en/businesses/premiums-and-payment/clearances))
+- **Alberta WCB**: a clearance letter is valid for work done **up to the date of the letter** — WCB advises requesting one at hire and before each installment. ([wcb.ab.ca clearance letters](https://www.wcb.ab.ca/insurance-and-premiums/clearance-letters/))
+
+> **This is not legal advice.** It's a date-tracking assistant built on the rules above; confirm obligations with your broker, WSIB/WCB, or counsel.
+
+## Install
+
+```bash
+pip install clearancewatch
+```
+
+## Jobs file
+
+```json
+[
+  {
+    "name": "Kitchen reno",
+    "province": "ON",
+    "start": "2026-02-01",
+    "end": "2026-03-30",
+    "subs": [
+      {
+        "name": "Bob's Drywall",
+        "trade": "drywall",
+        "clearance": { "issuer": "WSIB", "number": "1234567", "issued": "2026-01-10", "expires": "2026-04-10" },
+        "insurance": { "provider": "Aviva", "policy": "GL-9", "coverage": "C$2M", "expires": "2026-12-31" },
+        "licences": [ { "name": "Fall protection", "expires": "2026-09-01" } ]
+      }
+    ]
+  }
+]
+```
+
+## Usage
+
+```bash
+clearancewatch audit jobs.json --on 2026-02-15 --within 30
+clearancewatch renewals jobs.json --within 30     # just what's coming due
+clearancewatch audit jobs.json --json             # machine-readable
+```
+
+```
+ERROR clearance_expires_during_job  Kitchen reno / Bob's Drywall: clearance expires 2026-03-15 before job end 2026-03-30...
+WARN  renewal_due                   Kitchen reno / Bob's Drywall: insurance expires 2026-03-05 (within 30 days)
+
+1 error(s), 1 warning(s) — FAIL
+```
+
+Exit `1` when any error-severity finding exists (missing/expired clearance, lapsed coverage, expired insurance or licence) — CI- and cron-friendly.
+
+## What it catches
+
+| Finding | Severity |
+|---|---|
+| `clearance_missing` / `clearance_expired` / `clearance_expires_during_job` | error |
+| `clearance_cover_lapsed` (Alberta letter predates ongoing work) | warn |
+| `issuer_mismatch` (ON job, WCB-AB clearance — or vice versa) | warn |
+| `insurance_missing` / `insurance_expired` | error |
+| `insurance_expires_during_job` | warn |
+| `licence_expired` | error |
+| `renewal_due` / `insurance_renewal_due` / `licence_renewal_due` (within `--within` days) | warn |
+
+## Python API
+
+```python
+import datetime as dt
+from clearancewatch import Job, audit
+
+job = Job.from_dict({...})
+for finding in audit(job, on=dt.date(2026, 2, 15), horizon=30):
+    print(finding.severity, finding.code, finding.detail)
+```
+
+`clearancewatch renewals` over a weekly cron gives you the "call these three subs" list before a gap becomes a deeming problem.
+
+## License
+
+MIT-style: use it, ship it, no warranty.

clearancewatch-0.1.0/pyproject.toml

@@ -0,0 +1,24 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "clearancewatch"
+version = "0.1.0"
+description = "Track subcontractor compliance per job: WSIB/WCB clearance coverage, insurance and licence expiry against the job calendar"
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+authors = [{ name = "calasdan-sketch" }]
+keywords = ["wsib", "wcb", "clearance", "compliance", "construction", "trades", "insurance"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Environment :: Console",
+    "Topic :: Office/Business",
+]
+
+[project.scripts]
+clearancewatch = "clearancewatch.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]

clearancewatch-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

clearancewatch-0.1.0/src/clearancewatch/__init__.py

@@ -0,0 +1,16 @@
+"""clearancewatch — per-job subcontractor compliance: clearances, insurance, licences.
+
+Not legal advice. Rules modelled from official sources (see README), verified
+October 2026: WSIB clearances are valid up to 90 days and a principal must hold
+a valid clearance for the whole job; WCB Alberta clearance letters cover work up
+to the date of the letter.
+"""
+
+from .model import Clearance, Insurance, Job, Licence, Subcontractor
+from .audit import Finding, audit, renewals
+
+__version__ = "0.1.0"
+__all__ = [
+    "Job", "Subcontractor", "Clearance", "Insurance", "Licence",
+    "audit", "renewals", "Finding", "__version__",
+]

clearancewatch-0.1.0/src/clearancewatch/audit.py

@@ -0,0 +1,140 @@
+"""Audit a job's subcontractors against the job calendar.
+
+Severity model: things that expose the principal to deeming/penalty risk are
+errors (missing or expired clearance, lapsed coverage, expired insurance or
+licence); things that are still legal today but will bite soon are warnings
+(expiring during the job, renewal horizon).
+"""
+from __future__ import annotations
+
+import datetime as dt
+from dataclasses import dataclass
+from typing import List
+
+from .model import Job, Subcontractor, WSIB_DEFAULT_VALID_DAYS
+
+
+@dataclass(frozen=True)
+class Finding:
+    severity: str  # error | warn
+    code: str
+    subject: str   # "job / sub"
+    detail: str
+
+    def as_dict(self):
+        return {"severity": self.severity, "code": self.code,
+                "subject": self.subject, "detail": self.detail}
+
+
+def _issuer_family(issuer: str) -> str:
+    u = (issuer or "").upper()
+    if "WSIB" in u:
+        return "ON"
+    if u.startswith("WCB") or "WORKERS" in u:
+        return "AB" if ("AB" in u or "ALBERTA" in u) else "WCB"
+    return ""
+
+
+def _check_clearance(f: List[Finding], sub: Subcontractor, job: Job,
+                     on: dt.date, horizon: int, valid_days: int) -> None:
+    who = f"{job.name} / {sub.name}"
+    c = sub.clearance
+    if c is None or (not c.issuer and not c.issued and not c.expires):
+        f.append(Finding("error", "clearance_missing", who,
+                         "no clearance certificate on file"))
+        return
+
+    family = _issuer_family(c.issuer)
+    if job.province and family and family not in (job.province, "WCB"):
+        f.append(Finding("warn", "issuer_mismatch", who,
+                         f"job is in {job.province} but clearance issuer is {c.issuer!r}"))
+
+    if family == "AB" or c.covered_until is not None:
+        # Alberta letters: cover work done up to the letter date
+        cover = c.covered_until or c.issued
+        if cover is None:
+            f.append(Finding("error", "clearance_no_coverage_dates", who,
+                             "Alberta-style clearance needs issued/covered_until dates"))
+            return
+        horizon_date = job.end or on
+        if horizon_date > cover:
+            f.append(Finding("warn", "clearance_cover_lapsed", who,
+                             f"letter covers work up to {cover.isoformat()}; work continues past it "
+                             "(request a fresh clearance at the next installment)"))
+        return
+
+    expiry = c.effective_expiry(valid_days)
+    if expiry is None:
+        f.append(Finding("error", "clearance_no_expiry", who,
+                         "clearance has neither expiry nor issue date"))
+        return
+    if expiry < on:
+        f.append(Finding("error", "clearance_expired", who,
+                         f"clearance expired {expiry.isoformat()}"))
+    elif job.end and expiry < job.end:
+        f.append(Finding("error", "clearance_expires_during_job", who,
+                         f"clearance expires {expiry.isoformat()} before job end {job.end.isoformat()}; "
+                         "a principal must hold valid clearance for the whole job"))
+    elif (expiry - on).days <= horizon:
+        f.append(Finding("warn", "renewal_due", who,
+                         f"clearance expires {expiry.isoformat()} (within {horizon} days)"))
+
+
+def _check_insurance(f: List[Finding], sub: Subcontractor, job: Job,
+                     on: dt.date, horizon: int) -> None:
+    who = f"{job.name} / {sub.name}"
+    ins = sub.insurance
+    if ins is None or not (ins.provider or ins.policy):
+        f.append(Finding("error", "insurance_missing", who, "no insurance on file"))
+        return
+    if ins.expires is None:
+        f.append(Finding("warn", "insurance_no_expiry", who, "insurance has no expiry date recorded"))
+        return
+    if ins.expires < on:
+        f.append(Finding("error", "insurance_expired", who,
+                         f"insurance expired {ins.expires.isoformat()}"))
+    elif job.end and ins.expires < job.end:
+        f.append(Finding("warn", "insurance_expires_during_job", who,
+                         f"insurance expires {ins.expires.isoformat()} before job end"))
+    elif (ins.expires - on).days <= horizon:
+        f.append(Finding("warn", "insurance_renewal_due", who,
+                         f"insurance expires {ins.expires.isoformat()} (within {horizon} days)"))
+
+
+def _check_licences(f: List[Finding], sub: Subcontractor, job: Job, on: dt.date, horizon: int) -> None:
+    who = f"{job.name} / {sub.name}"
+    for lic in sub.licences:
+        label = lic.name or "licence"
+        if lic.expires is None:
+            f.append(Finding("warn", "licence_no_expiry", who, f"{label}: no expiry recorded"))
+            continue
+        if lic.expires < on:
+            f.append(Finding("error", "licence_expired", who,
+                             f"{label} expired {lic.expires.isoformat()}"))
+        elif job.end and lic.expires < job.end:
+            f.append(Finding("warn", "licence_expires_during_job", who,
+                             f"{label} expires {lic.expires.isoformat()} before job end"))
+        elif (lic.expires - on).days <= horizon:
+            f.append(Finding("warn", "licence_renewal_due", who,
+                             f"{label} expires {lic.expires.isoformat()} (within {horizon} days)"))
+
+
+def audit(job: Job, on: dt.date | None = None, horizon: int = 30,
+          valid_days: int = WSIB_DEFAULT_VALID_DAYS) -> List[Finding]:
+    """All compliance findings for one job as of ``on`` (default: today)."""
+    on = on or dt.date.today()
+    out: List[Finding] = []
+    for sub in job.subs:
+        _check_clearance(out, sub, job, on, horizon, valid_days)
+        _check_insurance(out, sub, job, on, horizon)
+        _check_licences(out, sub, job, on, horizon)
+    return out
+
+
+def renewals(jobs: List[Job], within: int = 30, on: dt.date | None = None) -> List[Finding]:
+    """Everything across jobs that needs a renewal touch within ``within`` days."""
+    on = on or dt.date.today()
+    out: List[Finding] = []
+    for job in jobs:
+        out.extend(f for f in audit(job, on=on, horizon=within) if "due" in f.code or "lapsed" in f.code)
+    return out

clearancewatch-0.1.0/src/clearancewatch/cli.py

@@ -0,0 +1,71 @@
+"""clearancewatch CLI: audit jobs.json for compliance gaps."""
+from __future__ import annotations
+
+import argparse
+import datetime as dt
+import json
+import sys
+from typing import List
+
+from . import __version__
+from .audit import audit, renewals
+from .model import Job
+
+
+def load_jobs(path: str) -> List[Job]:
+    try:
+        with open(path, encoding="utf-8") as fh:
+            data = json.load(fh)
+    except FileNotFoundError:
+        raise SystemExit(f"clearancewatch: not found: {path}")
+    except json.JSONDecodeError as e:
+        raise SystemExit(f"clearancewatch: invalid JSON: {e}")
+    if isinstance(data, dict):
+        data = data.get("jobs", [data])
+    return [Job.from_dict(d) for d in data]
+
+
+def main(argv: list[str] | None = None) -> int:
+    ap = argparse.ArgumentParser(
+        prog="clearancewatch",
+        description="Audit subcontractor clearance/insurance/licence coverage against job calendars.",
+    )
+    ap.add_argument("--version", action="version", version=f"clearancewatch {__version__}")
+    sub = ap.add_subparsers(dest="cmd", required=True)
+
+    a = sub.add_parser("audit", help="full audit; exit 1 when any error-severity finding exists")
+    a.add_argument("jobs", help="jobs JSON file (list, or {\"jobs\": [...]})")
+    a.add_argument("--on", metavar="YYYY-MM-DD", help="audit date (default: today)")
+    a.add_argument("--within", type=int, default=30, help="renewal horizon in days (default 30)")
+    a.add_argument("--json", action="store_true")
+
+    r = sub.add_parser("renewals", help="only what's due soon; exit 1 if anything is due")
+    r.add_argument("jobs")
+    r.add_argument("--within", type=int, default=30)
+    r.add_argument("--on", metavar="YYYY-MM-DD")
+    r.add_argument("--json", action="store_true")
+
+    args = ap.parse_args(argv)
+    on = dt.date.fromisoformat(args.on) if args.on else None
+    jobs = load_jobs(args.jobs)
+
+    if args.cmd == "audit":
+        findings = [f for job in jobs for f in audit(job, on=on, horizon=args.within)]
+    else:
+        findings = renewals(jobs, within=args.within, on=on)
+
+    errors = [f for f in findings if f.severity == "error"]
+    warns = [f for f in findings if f.severity == "warn"]
+    if args.json:
+        print(json.dumps({"errors": len(errors), "warnings": len(warns),
+                          "findings": [f.as_dict() for f in findings]}, indent=2))
+    else:
+        for f in findings:
+            print(f"{f.severity.upper():5} {f.code:28} {f.subject}: {f.detail}")
+        print(f"\n{len(errors)} error(s), {len(warns)} warning(s) — "
+              f"{'FAIL' if errors else 'PASS'}")
+    return 1 if errors else 0
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())

clearancewatch-0.1.0/src/clearancewatch/model.py

@@ -0,0 +1,110 @@
+"""Data model: jobs, subcontractors, and the documents that keep them legal."""
+from __future__ import annotations
+
+import datetime as dt
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
+
+WSIB_DEFAULT_VALID_DAYS = 90  # WSIB: clearance certificates valid up to 90 days
+
+
+def parse_date(value: Optional[str]) -> Optional[dt.date]:
+    if value in (None, ""):
+        return None
+    return dt.date.fromisoformat(str(value))
+
+
+@dataclass
+class Clearance:
+    """A workers'-compensation clearance certificate.
+
+    Ontario (WSIB): has a real expiry — ``expires``, defaulting to issued +
+    90 days when not stated.
+    Alberta (WCB): a clearance letter covers work done UP TO the date of the
+    letter — model that as ``covered_until`` (defaults to ``issued``).
+    """
+
+    issuer: str = ""            # e.g. "WSIB", "WCB-AB"
+    number: str = ""
+    issued: Optional[dt.date] = None
+    expires: Optional[dt.date] = None
+    covered_until: Optional[dt.date] = None  # Alberta-style letter coverage
+
+    @classmethod
+    def from_dict(cls, d: Dict[str, Any]) -> "Clearance":
+        return cls(issuer=d.get("issuer", ""), number=d.get("number", ""),
+                   issued=parse_date(d.get("issued")), expires=parse_date(d.get("expires")),
+                   covered_until=parse_date(d.get("covered_until")))
+
+    def effective_expiry(self, valid_days: int = WSIB_DEFAULT_VALID_DAYS) -> Optional[dt.date]:
+        if self.expires:
+            return self.expires
+        if self.issued and self.covered_until is None:
+            return self.issued + dt.timedelta(days=valid_days)
+        return self.covered_until or self.expires
+
+
+@dataclass
+class Insurance:
+    provider: str = ""
+    policy: str = ""
+    coverage: str = ""          # e.g. "C$2M liability"
+    expires: Optional[dt.date] = None
+
+    @classmethod
+    def from_dict(cls, d: Dict[str, Any]) -> "Insurance":
+        return cls(provider=d.get("provider", ""), policy=d.get("policy", ""),
+                   coverage=d.get("coverage", ""), expires=parse_date(d.get("expires")))
+
+
+@dataclass
+class Licence:
+    name: str = ""              # e.g. "309A electrical"
+    number: str = ""
+    authority: str = ""         # e.g. "TSSA", "ESA"
+    expires: Optional[dt.date] = None
+
+    @classmethod
+    def from_dict(cls, d: Dict[str, Any]) -> "Licence":
+        return cls(name=d.get("name", ""), number=d.get("number", ""),
+                   authority=d.get("authority", ""), expires=parse_date(d.get("expires")))
+
+
+@dataclass
+class Subcontractor:
+    name: str
+    province: str = ""
+    trade: str = ""
+    clearance: Optional[Clearance] = None
+    insurance: Optional[Insurance] = None
+    licences: List[Licence] = field(default_factory=list)
+
+    @classmethod
+    def from_dict(cls, d: Dict[str, Any]) -> "Subcontractor":
+        return cls(
+            name=d.get("name", "unnamed sub"),
+            province=d.get("province", ""),
+            trade=d.get("trade", ""),
+            clearance=Clearance.from_dict(d["clearance"]) if d.get("clearance") else None,
+            insurance=Insurance.from_dict(d["insurance"]) if d.get("insurance") else None,
+            licences=[Licence.from_dict(x) for x in d.get("licences", [])],
+        )
+
+
+@dataclass
+class Job:
+    name: str
+    province: str = ""
+    start: Optional[dt.date] = None
+    end: Optional[dt.date] = None  # None = ongoing
+    subs: List[Subcontractor] = field(default_factory=list)
+
+    @classmethod
+    def from_dict(cls, d: Dict[str, Any]) -> "Job":
+        return cls(
+            name=d.get("name", "unnamed job"),
+            province=d.get("province", ""),
+            start=parse_date(d.get("start")),
+            end=parse_date(d.get("end")),
+            subs=[Subcontractor.from_dict(s) for s in d.get("subs", d.get("subcontractors", []))],
+        )

clearancewatch-0.1.0/src/clearancewatch.egg-info/PKG-INFO

@@ -0,0 +1,99 @@
+Metadata-Version: 2.4
+Name: clearancewatch
+Version: 0.1.0
+Summary: Track subcontractor compliance per job: WSIB/WCB clearance coverage, insurance and licence expiry against the job calendar
+Author: calasdan-sketch
+License-Expression: MIT
+Keywords: wsib,wcb,clearance,compliance,construction,trades,insurance
+Classifier: Programming Language :: Python :: 3
+Classifier: Environment :: Console
+Classifier: Topic :: Office/Business
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# clearancewatch
+
+**A principal must hold valid workers'-comp coverage for every sub — for the whole job.** `clearancewatch` audits subcontractor compliance documents against the job calendar and tells you what's expired, what expires mid-job, and what's coming up for renewal.
+
+Rules modelled from official sources (verified October 2026):
+
+- **Ontario WSIB**: clearance certificates are valid **up to 90 days**; WSIB states a principal must ensure a valid clearance is in place for the **full length of a job**. ([wsib.ca clearances](https://www.wsib.ca/en/businesses/premiums-and-payment/clearances))
+- **Alberta WCB**: a clearance letter is valid for work done **up to the date of the letter** — WCB advises requesting one at hire and before each installment. ([wcb.ab.ca clearance letters](https://www.wcb.ab.ca/insurance-and-premiums/clearance-letters/))
+
+> **This is not legal advice.** It's a date-tracking assistant built on the rules above; confirm obligations with your broker, WSIB/WCB, or counsel.
+
+## Install
+
+```bash
+pip install clearancewatch
+```
+
+## Jobs file
+
+```json
+[
+  {
+    "name": "Kitchen reno",
+    "province": "ON",
+    "start": "2026-02-01",
+    "end": "2026-03-30",
+    "subs": [
+      {
+        "name": "Bob's Drywall",
+        "trade": "drywall",
+        "clearance": { "issuer": "WSIB", "number": "1234567", "issued": "2026-01-10", "expires": "2026-04-10" },
+        "insurance": { "provider": "Aviva", "policy": "GL-9", "coverage": "C$2M", "expires": "2026-12-31" },
+        "licences": [ { "name": "Fall protection", "expires": "2026-09-01" } ]
+      }
+    ]
+  }
+]
+```
+
+## Usage
+
+```bash
+clearancewatch audit jobs.json --on 2026-02-15 --within 30
+clearancewatch renewals jobs.json --within 30     # just what's coming due
+clearancewatch audit jobs.json --json             # machine-readable
+```
+
+```
+ERROR clearance_expires_during_job  Kitchen reno / Bob's Drywall: clearance expires 2026-03-15 before job end 2026-03-30...
+WARN  renewal_due                   Kitchen reno / Bob's Drywall: insurance expires 2026-03-05 (within 30 days)
+
+1 error(s), 1 warning(s) — FAIL
+```
+
+Exit `1` when any error-severity finding exists (missing/expired clearance, lapsed coverage, expired insurance or licence) — CI- and cron-friendly.
+
+## What it catches
+
+| Finding | Severity |
+|---|---|
+| `clearance_missing` / `clearance_expired` / `clearance_expires_during_job` | error |
+| `clearance_cover_lapsed` (Alberta letter predates ongoing work) | warn |
+| `issuer_mismatch` (ON job, WCB-AB clearance — or vice versa) | warn |
+| `insurance_missing` / `insurance_expired` | error |
+| `insurance_expires_during_job` | warn |
+| `licence_expired` | error |
+| `renewal_due` / `insurance_renewal_due` / `licence_renewal_due` (within `--within` days) | warn |
+
+## Python API
+
+```python
+import datetime as dt
+from clearancewatch import Job, audit
+
+job = Job.from_dict({...})
+for finding in audit(job, on=dt.date(2026, 2, 15), horizon=30):
+    print(finding.severity, finding.code, finding.detail)
+```
+
+`clearancewatch renewals` over a weekly cron gives you the "call these three subs" list before a gap becomes a deeming problem.
+
+## License
+
+MIT-style: use it, ship it, no warranty.

clearancewatch-0.1.0/src/clearancewatch.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+LICENSE
+README.md
+pyproject.toml
+src/clearancewatch/__init__.py
+src/clearancewatch/audit.py
+src/clearancewatch/cli.py
+src/clearancewatch/model.py
+src/clearancewatch.egg-info/PKG-INFO
+src/clearancewatch.egg-info/SOURCES.txt
+src/clearancewatch.egg-info/dependency_links.txt
+src/clearancewatch.egg-info/entry_points.txt
+src/clearancewatch.egg-info/top_level.txt
+tests/test_audit.py
+tests/test_cli.py

clearancewatch-0.1.0/src/clearancewatch.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

clearancewatch-0.1.0/src/clearancewatch.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+clearancewatch = clearancewatch.cli:main

clearancewatch-0.1.0/src/clearancewatch.egg-info/top_level.txt

@@ -0,0 +1 @@
+clearancewatch

clearancewatch-0.1.0/tests/test_audit.py

@@ -0,0 +1,116 @@
+"""Audit-rule tests with pinned dates."""
+import datetime as dt
+
+from clearancewatch.audit import audit, renewals
+from clearancewatch.model import Clearance, Insurance, Job, Licence, Subcontractor
+
+D = dt.date.fromisoformat
+
+
+def on_job(subs, start="2026-02-01", end="2026-03-30", province="ON", name="Job A"):
+    return Job(name=name, province=province, start=D(start), end=D(end) if end else None, subs=subs)
+
+
+def on_sub(**kw):
+    base = dict(name="Bob's Drywall", province="ON",
+                clearance=Clearance(issuer="WSIB", number="123", issued=D("2026-01-10"),
+                                    expires=D("2026-04-10")),
+                insurance=Insurance(provider="Aviva", policy="P-1", expires=D("2026-12-31")))
+    base.update(kw)
+    return Subcontractor(**base)
+
+
+def codes(findings):
+    return [f.code for f in findings]
+
+
+def test_happy_path_clean():
+    findings = audit(on_job([on_sub()]), on=D("2026-02-15"))
+    assert findings == [], findings
+
+
+def test_expiry_defaults_to_90_days_for_wsib():
+    c = Clearance(issuer="WSIB", issued=D("2026-01-10"))
+    assert c.effective_expiry() == D("2026-04-10")
+
+
+def test_expired_clearance():
+    sub = on_sub(clearance=Clearance(issuer="WSIB", issued=D("2025-06-01"), expires=D("2025-08-29")))
+    findings = audit(on_job([sub]), on=D("2026-02-15"))
+    assert "clearance_expired" in codes(findings)
+
+
+def test_clearance_expires_during_job():
+    sub = on_sub(clearance=Clearance(issuer="WSIB", issued=D("2026-01-20"), expires=D("2026-03-15")))
+    findings = audit(on_job([sub]), on=D("2026-02-15"))
+    assert "clearance_expires_during_job" in codes(findings)
+
+
+def test_missing_clearance_and_insurance():
+    sub = Subcontractor(name="NoDocs", clearance=None, insurance=None)
+    found = codes(audit(on_job([sub]), on=D("2026-02-15")))
+    assert "clearance_missing" in found and "insurance_missing" in found
+
+
+def test_renewal_due_within_horizon():
+    # expiry must sit after job end (else during-job error rightly fires first)
+    sub = on_sub(clearance=Clearance(issuer="WSIB", issued=D("2026-01-20"), expires=D("2026-03-10")))
+    job = on_job([sub], end="2026-03-05")
+    found = codes(audit(job, on=D("2026-02-15"), horizon=30))
+    assert "renewal_due" in found
+    assert "clearance_expired" not in found and "clearance_expires_during_job" not in found
+
+
+def test_alberta_letter_covers_only_up_to_its_date():
+    sub = on_sub(province="AB",
+                 clearance=Clearance(issuer="WCB-AB", number="L-9", issued=D("2026-01-05"),
+                                     covered_until=D("2026-03-05")))
+    job = on_job([sub], start="2026-01-10", end="2026-06-01", province="AB")
+    found = codes(audit(job, on=D("2026-02-15")))
+    assert "clearance_cover_lapsed" in found
+
+
+def test_alberta_letter_current_passes():
+    sub = on_sub(province="AB",
+                 clearance=Clearance(issuer="WCB-AB", issued=D("2026-03-01"), covered_until=D("2026-12-31")))
+    job = on_job([sub], start="2026-01-10", end="2026-06-01", province="AB")
+    assert audit(job, on=D("2026-02-15")) == []
+
+
+def test_issuer_mismatch_warns():
+    sub = on_sub(clearance=Clearance(issuer="WCB-AB", issued=D("2026-01-05"), covered_until=D("2026-12-31")))
+    found = codes(audit(on_job([sub], province="ON"), on=D("2026-02-15")))
+    assert "issuer_mismatch" in found
+
+
+def test_licence_expired_and_due():
+    sub = on_sub(licences=[Licence(name="309A electrical", expires=D("2025-12-01")),
+                           Licence(name="Fall protection", expires=D("2026-03-14"))])
+    job = on_job([sub], end="2026-03-10")  # due licence outlives the job, lands in the horizon
+    found = codes(audit(job, on=D("2026-02-15")))
+    assert "licence_expired" in found and "licence_renewal_due" in found
+
+
+def test_ongoing_job_uses_audit_date():
+    sub = on_sub(clearance=Clearance(issuer="WSIB", issued=D("2026-01-20"), expires=D("2026-03-15")))
+    job = on_job([sub], end=None)  # ongoing
+    found = codes(audit(job, on=D("2026-04-01")))
+    assert "clearance_expired" in found
+
+
+def test_insurance_during_job_is_warning():
+    sub = on_sub(insurance=Insurance(provider="Aviva", expires=D("2026-03-10")))
+    findings = audit(on_job([sub]), on=D("2026-02-15"))
+    f = next(x for x in findings if x.code == "insurance_expires_during_job")
+    assert f.severity == "warn"
+
+
+def test_renewals_filter():
+    jobs = [
+        on_job([on_sub(clearance=Clearance(issuer="WSIB", issued=D("2026-01-20"), expires=D("2026-03-10")))],
+               end="2026-03-05"),  # renewal due within 30 days of 02-15
+        on_job([on_sub()], name="Job B"),  # nothing due
+    ]
+    due = renewals(jobs, within=30, on=D("2026-02-15"))
+    assert all("due" in f.code or "lapsed" in f.code for f in due)
+    assert len(due) == 1

clearancewatch-0.1.0/tests/test_cli.py

@@ -0,0 +1,60 @@
+"""CLI tests."""
+import json
+
+from clearancewatch.cli import main
+
+
+def write_jobs(tmp, jobs):
+    p = tmp / "jobs.json"
+    p.write_text(json.dumps(jobs), encoding="utf-8")
+    return str(p)
+
+
+GOOD = {
+    "name": "Kitchen reno",
+    "province": "ON",
+    "start": "2026-02-01",
+    "end": "2026-03-30",
+    "subs": [{
+        "name": "Bob's Drywall",
+        "clearance": {"issuer": "WSIB", "number": "123", "issued": "2026-01-10", "expires": "2026-04-10"},
+        "insurance": {"provider": "Aviva", "policy": "P-1", "expires": "2026-12-31"},
+    }],
+}
+
+
+def test_audit_clean(tmp_path, capsys):
+    assert main(["audit", write_jobs(tmp_path, [GOOD]), "--on", "2026-02-15"]) == 0
+    assert "PASS" in capsys.readouterr().out
+
+
+def test_audit_errors_fail_with_json(tmp_path, capsys):
+    bad = dict(GOOD, subs=[{"name": "NoDocs"}])
+    code = main(["audit", write_jobs(tmp_path, [bad]), "--on", "2026-02-15", "--json"])
+    out = json.loads(capsys.readouterr().out)
+    assert code == 1 and out["errors"] >= 2
+    assert any(f["code"] == "clearance_missing" for f in out["findings"])
+
+
+def test_jobs_wrapper_dict(tmp_path, capsys):
+    p = tmp_path / "jobs.json"
+    p.write_text(json.dumps({"jobs": [GOOD]}), encoding="utf-8")
+    assert main(["audit", str(p), "--on", "2026-02-15"]) == 0
+
+
+def test_renewals_only_due(tmp_path, capsys):
+    due = dict(GOOD, end="2026-02-28",  # job ends before the expiry -> renewal_due, not during-job
+               subs=[dict(GOOD["subs"][0],
+                          clearance={"issuer": "WSIB", "issued": "2026-01-20", "expires": "2026-03-10"})])
+    assert main(["renewals", write_jobs(tmp_path, [due, GOOD]), "--within", "30", "--on", "2026-02-15"]) == 0
+    out = capsys.readouterr().out
+    assert "renewal_due" in out and out.count("WARN") == 1
+
+
+def test_missing_file(tmp_path):
+    try:
+        main(["audit", str(tmp_path / "nope.json")])
+        raised = False
+    except SystemExit as e:
+        raised = True
+    assert raised