diff --git a/docs/superpowers/plans/2026-09-11-project-month-week.md b/docs/superpowers/plans/2026-09-11-project-month-week.md
new file mode 100644
index 0000000..75a0db3
--- /dev/null
+++ b/docs/superpowers/plans/2026-09-11-project-month-week.md
@@ -0,0 +1,1769 @@
+# Project month/week filter — Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Let every site define its own "work month" (e.g. the 21st of one calendar month through the 20th of the next, not the 1st–30th), then tag every row on Timesheets, Delivery Notes, Purchase Orders, and Fuel Logs with which project Month/Week it falls in, and add a Today / This week / This month / All time filter to each of those four pages.
+
+**Architecture:** One new PocketBase field (`sites.work_month_start_day`) plus the existing `sites.job_start_date` are the only inputs. One new pure, fully-tested module (`src/lib/project-calendar.ts`) does all the date-bucketing math and is the single place the "which work-month cycle does this date fall in" logic lives. Each of the four sheet pages calls it once per row in its existing server-side loader (no new data fetching — every loader already fetches full `sites` records) and renders the result via one shared badge component. The filter itself reuses each page's own existing local `SelectFilter` (or raw `<Select>`) pattern rather than introducing a new shared filter component, matching how this codebase already tolerates that small duplication across `timesheets-view.tsx`, `delivery-notes-view.tsx`, and `fuel-logs-view.tsx`.
+
+**Tech Stack:** Next.js 16 App Router (Server Component loaders), TypeScript, PocketBase, vitest.
+
+**Design decisions locked in before writing this plan (confirmed with the user):**
+- **Day-of-month overflow:** if a site's start day (e.g. 31) doesn't exist in a given month (e.g. February), the cycle boundary clamps to that month's last real day. It does not roll forward.
+- **Week numbering:** simple 7-day blocks counted from the work-month's own start day (Week 1 = days 1–7 of the cycle, Week 2 = days 8–14, etc.), not aligned to the Monday–Sunday calendar week. Capped at Week 4 — any trailing days in a longer cycle (a 31-day cycle can run a few days past day 28) stay part of Week 4 rather than spawning a Week 5.
+- **Display:** every row gets a visible "M{month} · W{week}" badge, in addition to the filter.
+- **Scope:** Timesheets, Delivery Notes, Purchase Orders, Fuel Logs. (Vehicles/Equipment pages are per-asset dashboards, not per-entry sheets, and are explicitly out of scope.)
+- **Anchor date:** this feature uses `sites.job_start_date` directly — it does **not** fall back to "earliest activity date" the way `resolveSiteStartDate` (used elsewhere for burn-rate projections) does. If a site has no `job_start_date` set, every row for that site shows "—" instead of a Month/Week badge, and only matches the "All time" filter. This is a deliberate scope cut: reusing the multi-collection fallback would mean every sheet's loader fetching fixed costs/income/etc. it doesn't otherwise need, for a feature whose entire premise is "know exactly when the work-month started." Today, PocketBase has exactly one site and its `job_start_date` is blank — filling it in via the already-existing site edit form is a one-time, 30-second prerequisite for this feature to show anything, not a code gap.
+
+---
+
+## File Structure
+
+| File | Change |
+| --- | --- |
+| `scripts/pb-bootstrap-schema.py` | **Modify** — add `work_month_start_day` to the `sites` field list (keeps fresh installs in sync) |
+| `scripts/migrations/2026-09-11-add-site-work-month-field.py` | **Create** — idempotent migration for the live PocketBase instance |
+| `src/lib/project-calendar.ts` | **Create** — the work-month/week bucketing math |
+| `src/lib/project-calendar.test.ts` | **Create** |
+| `src/components/project-period-badge.tsx` | **Create** — shared "M{x} · W{y}" badge |
+| `src/app/api/sites/route.ts` | **Modify** — allow `work_month_start_day` on create |
+| `src/app/api/sites/[id]/route.ts` | **Modify** — allow `work_month_start_day` on update |
+| `src/components/site-form-dialog.tsx` | **Modify** — add the "Work month starts on day" field |
+| `src/app/dashboard/workforce/timesheets/page.tsx` | **Modify** — attach `projectPeriod` per row |
+| `src/app/dashboard/workforce/timesheets/timesheets-view.tsx` | **Modify** — period filter + badge column |
+| `src/app/dashboard/financial/delivery-notes/page.tsx` | **Modify** — attach `projectPeriod` per row |
+| `src/app/dashboard/financial/delivery-notes/delivery-notes-view.tsx` | **Modify** — period filter + badge column |
+| `src/app/dashboard/financial/purchase-orders/page.tsx` | **Modify** — add `siteId`/`dateUploaded` to `PoRow`, attach `projectPeriod` |
+| `src/app/dashboard/financial/purchase-orders/purchasing-view.tsx` | **Modify** — period filter + badge on the PO card |
+| `src/app/dashboard/plant/fuel-logs/page.tsx` | **Modify** — attach `projectPeriod` per row |
+| `src/app/dashboard/plant/fuel-logs/fuel-logs-view.tsx` | **Modify** — period filter + badge column |
+
+---
+
+### Task 1: PocketBase schema — `sites.work_month_start_day`
+
+**Files:**
+- Modify: `scripts/pb-bootstrap-schema.py`
+- Create: `scripts/migrations/2026-09-11-add-site-work-month-field.py`
+
+- [ ] **Step 1: Add the field to the bootstrap schema**
+
+In `scripts/pb-bootstrap-schema.py`, find `DEFS["sites"]` (currently ends with `field("job_start_date", "date", required=False),`) and add one line directly after it:
+
+```python
+DEFS["sites"] = {
+    "name": "SITES", "type": "base",
+    "fields": [
+        field("project_code", "text", required=True, min=1, max=64),
+        field("name", "text", required=False),
+        field("duration", "text", required=False),
+        field("contract_value", "number", required=False),
+        field("work_hours", "number", required=False),
+        field("hours_per_week", "number", required=False),
+        field("wages_hours_per_day", "number", required=False),
+        field("latitude", "number", required=False),
+        field("longitude", "number", required=False),
+        field("job_start_date", "date", required=False),
+        # How the site counts its own "work months" — e.g. 21 means each
+        # work-month runs the 21st through the 20th of the next calendar
+        # month, not the 1st–30th. Unset (or 1) means ordinary calendar
+        # months. See src/lib/project-calendar.ts.
+        field("work_month_start_day", "number", required=False, min=1, max=31),
+    ],
+    "indexes": [
+        "CREATE UNIQUE INDEX `idx_sites_project_code` ON `sites` (`project_code`)",
+    ],
+}
+```
+
+- [ ] **Step 2: Write the migration script**
+
+```python
+#!/usr/bin/env python3
+"""
+One-shot PocketBase migration applied via:
+
+  PB_URL=https://pb.mega.infra.apphub.co.za \\
+  PB_ADMIN_EMAIL=admin@mega.co.za \\
+  PB_ADMIN_PASSWORD=... \\
+  python3 scripts/migrations/2026-09-11-add-site-work-month-field.py
+
+Adds sites.work_month_start_day (see
+docs/superpowers/specs/2026-09-11-project-month-week-design.md for why:
+some sites' "work months" don't run 1st-30th, they run e.g. 21st-21st).
+
+Strictly additive, and the field is not required — existing sites keep
+whatever value they have (empty means "ordinary calendar months").
+
+Idempotent: re-running skips the field if it already exists.
+"""
+import json
+import os
+import sys
+import urllib.error
+import urllib.request
+
+NEW_FIELD = {
+    "name": "work_month_start_day",
+    "type": "number",
+    "required": False,
+    "min": 1,
+    "max": 31,
+}
+
+
+def admin_auth(base_url: str) -> str:
+    body = json.dumps(
+        {
+            "identity": os.environ["PB_ADMIN_EMAIL"],
+            "password": os.environ["PB_ADMIN_PASSWORD"],
+        }
+    ).encode()
+    req = urllib.request.Request(
+        f"{base_url}/api/collections/_superusers/auth-with-password",
+        data=body,
+        headers={"Content-Type": "application/json"},
+        method="POST",
+    )
+    with urllib.request.urlopen(req) as resp:
+        return json.loads(resp.read())["token"]
+
+
+def get_collection(base_url: str, token: str, name: str):
+    req = urllib.request.Request(
+        f"{base_url}/api/collections/{name}", headers={"Authorization": token}
+    )
+    try:
+        with urllib.request.urlopen(req) as resp:
+            return json.loads(resp.read())
+    except urllib.error.HTTPError as e:
+        if e.code == 404:
+            return None
+        raise
+
+
+def patch_collection(base_url: str, token: str, name: str, body: dict):
+    req = urllib.request.Request(
+        f"{base_url}/api/collections/{name}",
+        data=json.dumps(body).encode(),
+        headers={"Authorization": token, "Content-Type": "application/json"},
+        method="PATCH",
+    )
+    try:
+        with urllib.request.urlopen(req) as resp:
+            return json.loads(resp.read())
+    except urllib.error.HTTPError as e:
+        raise RuntimeError(
+            f"PATCH {name} failed: {e.code} {e.read().decode() if e.fp else ''}"
+        ) from e
+
+
+def main() -> int:
+    base_url = os.environ.get("PB_URL", "http://127.0.0.1:8090").rstrip("/")
+    token = admin_auth(base_url)
+
+    coll = get_collection(base_url, token, "sites")
+    if not coll:
+        print(f"ERROR: collection 'sites' not found on {base_url}")
+        return 1
+
+    existing = coll.get("fields", [])
+    have = {f["name"] for f in existing}
+    if NEW_FIELD["name"] in have:
+        print("sites: no-op, work_month_start_day already present")
+    else:
+        print("sites: adding work_month_start_day")
+        patch_collection(base_url, token, "sites", {"fields": existing + [NEW_FIELD]})
+
+    final = get_collection(base_url, token, "sites")
+    print("\nFinal sites field list:")
+    print(f"  {sorted(f['name'] for f in final.get('fields', []))}")
+    print("\nMigration complete.")
+    return 0
+
+
+if __name__ == "__main__":
+    try:
+        sys.exit(main())
+    except KeyError as e:
+        print(
+            f"ERROR: missing environment variable {e}. "
+            f"Set PB_ADMIN_EMAIL and PB_ADMIN_PASSWORD.",
+            file=sys.stderr,
+        )
+        sys.exit(2)
+```
+
+- [ ] **Step 3: Run it against the live instance**
+
+```bash
+PB_URL=https://pb.mega.infra.apphub.co.za \
+PB_ADMIN_EMAIL="$POCKETBASE_ADMIN_EMAIL" \
+PB_ADMIN_PASSWORD="$POCKETBASE_ADMIN_PASSWORD" \
+python3 scripts/migrations/2026-09-11-add-site-work-month-field.py
+```
+Expected: `sites: adding work_month_start_day` then the final field list includes it. Re-running prints `sites: no-op, work_month_start_day already present`.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add scripts/pb-bootstrap-schema.py scripts/migrations/2026-09-11-add-site-work-month-field.py
+git commit -m "feat(sites): add work_month_start_day field"
+```
+
+---
+
+### Task 2: `project-calendar.ts` — the work-month/week math
+
+This is the one piece of genuinely new logic in this plan. Everything else is wiring.
+
+**Files:**
+- Create: `src/lib/project-calendar.ts`
+- Test: `src/lib/project-calendar.test.ts`
+
+- [ ] **Step 1: Write the failing tests**
+
+```typescript
+// src/lib/project-calendar.test.ts
+import { describe, expect, it } from "vitest";
+import {
+  deriveProjectPeriodLabel,
+  matchesProjectPeriodFilter,
+  resolveProjectPeriod,
+} from "./project-calendar";
+
+describe("resolveProjectPeriod", () => {
+  it("defaults to ordinary calendar months when no start day is given", () => {
+    // Site started 2026-01-05. With no work_month_start_day, the cycle
+    // that contains Jan 5 starts Jan 1 — Month 1 = January.
+    expect(resolveProjectPeriod("2026-01-20", "2026-01-05")).toEqual({
+      projectMonth: 1,
+      projectWeek: 3,
+    });
+    // March is Month 3 (Jan=1, Feb=2, Mar=3).
+    expect(resolveProjectPeriod("2026-03-10", "2026-01-05")).toEqual({
+      projectMonth: 3,
+      projectWeek: 2,
+    });
+  });
+
+  it("uses a custom start day (21st-to-21st cycles)", () => {
+    const start = "2026-02-21";
+    // Still inside the Feb21-Mar20 cycle -> Month 1.
+    expect(resolveProjectPeriod("2026-03-15", start, 21)).toEqual({
+      projectMonth: 1,
+      projectWeek: 4,
+    });
+    // Mar21 begins the next cycle -> Month 2, day 0 of that cycle -> Week 1.
+    expect(resolveProjectPeriod("2026-03-21", start, 21)).toEqual({
+      projectMonth: 2,
+      projectWeek: 1,
+    });
+  });
+
+  it("clamps an overflowing start day to the last real day of a short month", () => {
+    // Start day 31, site started 2026-01-31.
+    // Feb 2026 has 28 days, so that cycle's boundary clamps to Feb 28,
+    // not rolling into March.
+    const start = "2026-01-31";
+    // Still the Jan31-Feb27 cycle -> Month 1.
+    expect(resolveProjectPeriod("2026-02-15", start, 31)).toEqual({
+      projectMonth: 1,
+      projectWeek: 3,
+    });
+    // Feb 28 begins the next cycle (clamped) -> Month 2.
+    expect(resolveProjectPeriod("2026-02-28", start, 31)).toEqual({
+      projectMonth: 2,
+      projectWeek: 1,
+    });
+    // March 31 is back to a real 31st -> Month 3, no drift carried over.
+    expect(resolveProjectPeriod("2026-03-31", start, 31)).toEqual({
+      projectMonth: 3,
+      projectWeek: 1,
+    });
+  });
+
+  it("caps week numbering at 4 for a cycle longer than 28 days", () => {
+    // Jan31-Feb27 cycle is 28 days (clamped short) -> day 27 is week 4.
+    // Use a 31-day cycle instead: start day 1, January itself (31 days).
+    // Day 29 (0-indexed 28) -> floor(28/7)+1 = 5, capped to 4.
+    expect(resolveProjectPeriod("2026-01-29", "2026-01-01", 1)).toEqual({
+      projectMonth: 1,
+      projectWeek: 4,
+    });
+  });
+
+  it("returns null for a date before the site's start", () => {
+    expect(resolveProjectPeriod("2025-12-31", "2026-01-05")).toBeNull();
+  });
+
+  it("returns null when either date is missing or unparseable", () => {
+    expect(resolveProjectPeriod("", "2026-01-05")).toBeNull();
+    expect(resolveProjectPeriod("2026-01-05", "")).toBeNull();
+    expect(resolveProjectPeriod("not-a-date", "2026-01-05")).toBeNull();
+  });
+
+  it("treats an out-of-range start day as calendar-month default", () => {
+    // 0 and 32 are both invalid 1-31 values -> falls back to day 1.
+    expect(resolveProjectPeriod("2026-01-20", "2026-01-01", 0)).toEqual({
+      projectMonth: 1,
+      projectWeek: 3,
+    });
+    expect(resolveProjectPeriod("2026-01-20", "2026-01-01", 32)).toEqual({
+      projectMonth: 1,
+      projectWeek: 3,
+    });
+  });
+});
+
+describe("deriveProjectPeriodLabel", () => {
+  const NOW = new Date("2026-03-15T00:00:00.000Z");
+
+  it("returns null when the site has no job_start_date", () => {
+    expect(deriveProjectPeriodLabel("2026-03-10", {}, NOW)).toBeNull();
+  });
+
+  it("marks isToday only for an exact date match", () => {
+    const site = { job_start_date: "2026-01-01" };
+    const today = deriveProjectPeriodLabel("2026-03-15", site, NOW);
+    expect(today?.isToday).toBe(true);
+    const yesterday = deriveProjectPeriodLabel("2026-03-14", site, NOW);
+    expect(yesterday?.isToday).toBe(false);
+  });
+
+  it("marks isThisWeek and isThisMonth against the site's own cycle", () => {
+    const site = { job_start_date: "2026-02-21", work_month_start_day: 21 };
+    // "Now" (Mar 15) falls in Month 1, Week 4 of this site's cycle.
+    const sameWeek = deriveProjectPeriodLabel("2026-03-14", site, NOW);
+    expect(sameWeek?.isThisWeek).toBe(true);
+    expect(sameWeek?.isThisMonth).toBe(true);
+
+    const earlierThisMonth = deriveProjectPeriodLabel("2026-02-25", site, NOW);
+    expect(earlierThisMonth?.isThisWeek).toBe(false);
+    expect(earlierThisMonth?.isThisMonth).toBe(true);
+
+    const lastMonth = deriveProjectPeriodLabel("2026-02-20", site, NOW);
+    expect(lastMonth).toBeNull(); // before the site's start
+  });
+});
+
+describe("matchesProjectPeriodFilter", () => {
+  const label = {
+    projectMonth: 2,
+    projectWeek: 1,
+    isToday: false,
+    isThisWeek: true,
+    isThisMonth: true,
+  };
+
+  it("'all' always matches, even with no period", () => {
+    expect(matchesProjectPeriodFilter("all", null)).toBe(true);
+    expect(matchesProjectPeriodFilter("all", label)).toBe(true);
+  });
+
+  it("every other filter requires a period", () => {
+    expect(matchesProjectPeriodFilter("today", null)).toBe(false);
+    expect(matchesProjectPeriodFilter("week", null)).toBe(false);
+    expect(matchesProjectPeriodFilter("month", null)).toBe(false);
+  });
+
+  it("checks the matching boolean on the label", () => {
+    expect(matchesProjectPeriodFilter("today", label)).toBe(false);
+    expect(matchesProjectPeriodFilter("week", label)).toBe(true);
+    expect(matchesProjectPeriodFilter("month", label)).toBe(true);
+  });
+});
+```
+
+- [ ] **Step 2: Run the tests to verify they fail**
+
+Run: `npx vitest run src/lib/project-calendar.test.ts`
+Expected: FAIL — `Cannot find module './project-calendar'`
+
+- [ ] **Step 3: Write the implementation**
+
+```typescript
+// src/lib/project-calendar.ts
+/**
+ * A site's "work month" doesn't have to run the 1st-30th. One real site
+ * runs the 21st through the 20th of the next month; another runs the
+ * 15th through the 14th. `work_month_start_day` (1-31, unset = 1 =
+ * ordinary calendar months) is that anchor day. "Month 1" is whichever
+ * cycle contains the site's `job_start_date` — everything here is pure
+ * date math, no PocketBase access.
+ */
+
+const MS_PER_DAY = 86_400_000;
+
+export interface ProjectPeriod {
+  /** 1-indexed: the cycle containing the site's job_start_date is Month 1. */
+  projectMonth: number;
+  /** 1-indexed, capped at 4. Simple 7-day blocks from the cycle's own start. */
+  projectWeek: number;
+}
+
+export interface ProjectPeriodLabel extends ProjectPeriod {
+  /** The row's date is today (exact calendar-day match). */
+  isToday: boolean;
+  /** The row's date falls in the same project month+week as today, for this site. */
+  isThisWeek: boolean;
+  /** The row's date falls in the same project month as today, for this site. */
+  isThisMonth: boolean;
+}
+
+export interface ProjectPeriodSite {
+  job_start_date?: string | null;
+  work_month_start_day?: number | null;
+}
+
+export type ProjectPeriodFilterValue = "all" | "today" | "week" | "month";
+
+function parseIsoDateUtc(iso: string): number | null {
+  if (!iso) return null;
+  const d = new Date(iso);
+  if (Number.isNaN(d.getTime())) return null;
+  return Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), d.getUTCDate());
+}
+
+function daysInMonth(year: number, month0: number): number {
+  return new Date(Date.UTC(year, month0 + 1, 0)).getUTCDate();
+}
+
+function clampDay(year: number, month0: number, day: number): number {
+  return Math.min(day, daysInMonth(year, month0));
+}
+
+/** The UTC-midnight start of the work-month cycle that contains `dateUtcMs`. */
+function cycleStartContaining(dateUtcMs: number, startDay: number): number {
+  const d = new Date(dateUtcMs);
+  const y = d.getUTCFullYear();
+  const m = d.getUTCMonth();
+  const day = d.getUTCDate();
+  const anchorThisMonth = clampDay(y, m, startDay);
+  if (day >= anchorThisMonth) {
+    return Date.UTC(y, m, anchorThisMonth);
+  }
+  const prevM = m === 0 ? 11 : m - 1;
+  const prevY = m === 0 ? y - 1 : y;
+  return Date.UTC(prevY, prevM, clampDay(prevY, prevM, startDay));
+}
+
+/** The start of the cycle immediately after the one starting at `cycleStartMs`. */
+function nextCycleStart(cycleStartMs: number, startDay: number): number {
+  const d = new Date(cycleStartMs);
+  const y = d.getUTCFullYear();
+  const m = d.getUTCMonth();
+  const nextM = m === 11 ? 0 : m + 1;
+  const nextY = m === 11 ? y + 1 : y;
+  return Date.UTC(nextY, nextM, clampDay(nextY, nextM, startDay));
+}
+
+/**
+ * Which work-month/week a date falls in, for a site whose work-months
+ * start on `workMonthStartDay` (default 1 = ordinary calendar months)
+ * and whose Month 1 is the cycle containing `siteStartDateISO`.
+ *
+ * Returns null if either date is missing/unparseable, or if `dateISO`
+ * is before the site's own start (out of range for this project).
+ */
+export function resolveProjectPeriod(
+  dateISO: string,
+  siteStartDateISO: string,
+  workMonthStartDay?: number,
+): ProjectPeriod | null {
+  const targetMs = parseIsoDateUtc(dateISO);
+  const anchorMs = parseIsoDateUtc(siteStartDateISO);
+  if (targetMs === null || anchorMs === null) return null;
+
+  const startDay =
+    workMonthStartDay != null && workMonthStartDay >= 1 && workMonthStartDay <= 31
+      ? Math.floor(workMonthStartDay)
+      : 1;
+
+  const anchorCycleStart = cycleStartContaining(anchorMs, startDay);
+  const targetCycleStart = cycleStartContaining(targetMs, startDay);
+  if (targetCycleStart < anchorCycleStart) return null;
+
+  let monthsElapsed = 0;
+  let cursor = anchorCycleStart;
+  while (cursor < targetCycleStart) {
+    cursor = nextCycleStart(cursor, startDay);
+    monthsElapsed++;
+  }
+
+  const dayOffset = Math.floor((targetMs - targetCycleStart) / MS_PER_DAY);
+  const projectWeek = Math.min(4, Math.floor(dayOffset / 7) + 1);
+
+  return { projectMonth: monthsElapsed + 1, projectWeek };
+}
+
+/**
+ * The full label for one row: its own Month/Week, plus whether it
+ * matches "today" / "this week" / "this month" for its site right now.
+ * Returns null if the site has no `job_start_date` set — there is
+ * nothing to anchor Month 1 to.
+ */
+export function deriveProjectPeriodLabel(
+  dateISO: string,
+  site: ProjectPeriodSite,
+  now: Date = new Date(),
+): ProjectPeriodLabel | null {
+  const startDate = site.job_start_date;
+  if (!startDate) return null;
+  const startDay = site.work_month_start_day ?? undefined;
+
+  const rowPeriod = resolveProjectPeriod(dateISO, startDate, startDay);
+  if (!rowPeriod) return null;
+
+  const todayISO = now.toISOString().slice(0, 10);
+  const todayPeriod = resolveProjectPeriod(todayISO, startDate, startDay);
+  if (!todayPeriod) return null;
+
+  return {
+    ...rowPeriod,
+    isToday: dateISO.slice(0, 10) === todayISO,
+    isThisWeek:
+      rowPeriod.projectMonth === todayPeriod.projectMonth &&
+      rowPeriod.projectWeek === todayPeriod.projectWeek,
+    isThisMonth: rowPeriod.projectMonth === todayPeriod.projectMonth,
+  };
+}
+
+/** "all" always matches; every other value requires a resolved period. */
+export function matchesProjectPeriodFilter(
+  filter: ProjectPeriodFilterValue,
+  period: ProjectPeriodLabel | null,
+): boolean {
+  if (filter === "all") return true;
+  if (!period) return false;
+  if (filter === "today") return period.isToday;
+  if (filter === "week") return period.isThisWeek;
+  return period.isThisMonth;
+}
+```
+
+- [ ] **Step 4: Run the tests to verify they pass**
+
+Run: `npx vitest run src/lib/project-calendar.test.ts`
+Expected: PASS (all cases)
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/lib/project-calendar.ts src/lib/project-calendar.test.ts
+git commit -m "feat(project-calendar): add work-month/week bucketing with tests"
+```
+
+---
+
+### Task 3: Shared badge component
+
+**Files:**
+- Create: `src/components/project-period-badge.tsx`
+
+- [ ] **Step 1: Write the component**
+
+```tsx
+// src/components/project-period-badge.tsx
+import { Badge } from "@/components/ui/badge";
+import type { ProjectPeriodLabel } from "@/lib/project-calendar";
+
+/**
+ * "M{month} · W{week}" tag for a row, or an em-dash when the row's site
+ * has no job_start_date set yet (see project-calendar.ts).
+ */
+export function ProjectPeriodBadge({ period }: { period: ProjectPeriodLabel | null }) {
+  if (!period) {
+    return <span className="text-xs text-muted-foreground">—</span>;
+  }
+  return (
+    <Badge variant="outline" className="font-mono text-[10px] whitespace-nowrap">
+      M{period.projectMonth} · W{period.projectWeek}
+    </Badge>
+  );
+}
+```
+
+- [ ] **Step 2: Commit**
+
+```bash
+git add src/components/project-period-badge.tsx
+git commit -m "feat(project-calendar): add shared Month/Week badge component"
+```
+
+---
+
+### Task 4: Site API routes — allow `work_month_start_day`
+
+**Files:**
+- Modify: `src/app/api/sites/route.ts`
+- Modify: `src/app/api/sites/[id]/route.ts`
+
+- [ ] **Step 1: Allow it on create**
+
+In `src/app/api/sites/route.ts`, the numeric-field validation loop currently reads:
+
+```typescript
+  for (const key of [
+    "contract_value",
+    "work_hours",
+    "hours_per_week",
+    "wages_hours_per_day",
+  ]) {
+    if (typeof payload[key] === "string" && payload[key] === "") {
+      delete payload[key];
+    }
+  }
+```
+
+And the field-copy loop just above it lists `"job_start_date"` last. Add `"work_month_start_day"` to that copy loop:
+
+```typescript
+  const payload: Record<string, unknown> = { project_code: projectCode };
+  for (const key of [
+    "name",
+    "duration",
+    "contract_value",
+    "work_hours",
+    "hours_per_week",
+    "wages_hours_per_day",
+    "job_start_date",
+    "work_month_start_day",
+  ]) {
+    if (body[key] !== undefined && body[key] !== null && body[key] !== "") {
+      payload[key] = body[key];
+    }
+  }
+
+  for (const key of [
+    "contract_value",
+    "work_hours",
+    "hours_per_week",
+    "wages_hours_per_day",
+    "work_month_start_day",
+  ]) {
+    if (typeof payload[key] === "string" && payload[key] === "") {
+      delete payload[key];
+    }
+  }
+```
+
+- [ ] **Step 2: Allow it on update**
+
+In `src/app/api/sites/[id]/route.ts`, the numeric-coercion loop currently reads:
+
+```typescript
+  for (const k of [
+    "contract_value",
+    "work_hours",
+    "hours_per_week",
+    "wages_hours_per_day",
+  ] as const) {
+    const v = body[k];
+    if (v === null || v === "") continue;
+    const n = typeof v === "number" ? v : Number(v);
+    if (Number.isFinite(n)) payload[k] = n;
+  }
+```
+
+Add `"work_month_start_day"` to that same list:
+
+```typescript
+  for (const k of [
+    "contract_value",
+    "work_hours",
+    "hours_per_week",
+    "wages_hours_per_day",
+    "work_month_start_day",
+  ] as const) {
+    const v = body[k];
+    if (v === null || v === "") continue;
+    const n = typeof v === "number" ? v : Number(v);
+    if (Number.isFinite(n)) payload[k] = n;
+  }
+```
+
+- [ ] **Step 3: Typecheck**
+
+Run: `npm run typecheck`
+Expected: no errors.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add src/app/api/sites/route.ts "src/app/api/sites/[id]/route.ts"
+git commit -m "feat(sites): accept work_month_start_day on create/update"
+```
+
+---
+
+### Task 5: Site form — add the field
+
+**Files:**
+- Modify: `src/components/site-form-dialog.tsx`
+
+- [ ] **Step 1: Add it to both interfaces**
+
+```typescript
+export interface SiteFormInitial {
+  id?: string;
+  project_code?: string;
+  name?: string;
+  duration?: string;
+  contract_value?: number | null;
+  work_hours?: number | null;
+  hours_per_week?: number | null;
+  wages_hours_per_day?: number | null;
+  job_start_date?: string | null;
+  work_month_start_day?: number | null;
+  latitude?: number | null;
+  longitude?: number | null;
+}
+
+export interface SiteTemplateOption {
+  id: string;
+  project_code: string;
+  name: string;
+  duration?: string;
+  contract_value?: number | null;
+  work_hours?: number | null;
+  hours_per_week?: number | null;
+  wages_hours_per_day?: number | null;
+  job_start_date?: string | null;
+  work_month_start_day?: number | null;
+}
+```
+
+- [ ] **Step 2: Clone it from a template**
+
+In the template-clone `useEffect`, add one line after `job_start_date`:
+
+```typescript
+    setForm((f) => ({
+      ...f,
+      duration: tpl.duration ?? f.duration,
+      contract_value:
+        tpl.contract_value != null ? String(tpl.contract_value) : f.contract_value,
+      work_hours: tpl.work_hours != null ? String(tpl.work_hours) : f.work_hours,
+      hours_per_week:
+        tpl.hours_per_week != null ? String(tpl.hours_per_week) : f.hours_per_week,
+      wages_hours_per_day:
+        tpl.wages_hours_per_day != null
+          ? String(tpl.wages_hours_per_day)
+          : f.wages_hours_per_day,
+      job_start_date: tpl.job_start_date ?? f.job_start_date,
+      work_month_start_day:
+        tpl.work_month_start_day != null
+          ? String(tpl.work_month_start_day)
+          : f.work_month_start_day,
+    }));
+```
+
+- [ ] **Step 3: Send it on create and edit**
+
+In the `submit` function's create branch:
+
+```typescript
+          body: JSON.stringify({
+            project_code: projectCode,
+            name: form.name.trim(),
+            duration: form.duration.trim() || undefined,
+            job_start_date: form.job_start_date || undefined,
+            work_month_start_day: numOrUndef(form.work_month_start_day),
+            contract_value: numOrUndef(form.contract_value),
+            work_hours: numOrUndef(form.work_hours),
+            hours_per_week: numOrUndef(form.hours_per_week),
+            wages_hours_per_day: numOrUndef(form.wages_hours_per_day),
+            latitude: form.latitude.trim() || undefined,
+            longitude: form.longitude.trim() || undefined,
+          }),
+```
+
+And the edit branch:
+
+```typescript
+          body: JSON.stringify({
+            name: form.name.trim(),
+            duration: form.duration.trim() || null,
+            job_start_date: form.job_start_date || null,
+            work_month_start_day: numOrUndef(form.work_month_start_day),
+            contract_value: numOrUndef(form.contract_value),
+            work_hours: numOrUndef(form.work_hours),
+            hours_per_week: numOrUndef(form.hours_per_week),
+            wages_hours_per_day: numOrUndef(form.wages_hours_per_day),
+            latitude: form.latitude.trim(),
+            longitude: form.longitude.trim(),
+          }),
+```
+
+- [ ] **Step 4: Add the input field**
+
+Directly after the "Job start date" `<Field>` block, add:
+
+```tsx
+            <Field
+              label="Work month starts on day"
+              hint="1–31. Leave blank for the 1st–30th (ordinary calendar months)"
+            >
+              <Input
+                type="number"
+                inputMode="numeric"
+                min="1"
+                max="31"
+                value={form.work_month_start_day}
+                onChange={(e) => setField("work_month_start_day", e.target.value)}
+                placeholder="1"
+              />
+            </Field>
+```
+
+- [ ] **Step 5: Wire the form state**
+
+```typescript
+interface FormState {
+  project_code: string;
+  name: string;
+  duration: string;
+  job_start_date: string;
+  work_month_start_day: string;
+  contract_value: string;
+  work_hours: string;
+  hours_per_week: string;
+  wages_hours_per_day: string;
+  latitude: string;
+  longitude: string;
+}
+
+function initialValues(initial?: SiteFormInitial): FormState {
+  return {
+    project_code: initial?.project_code ?? "",
+    name: initial?.name ?? "",
+    duration: initial?.duration ?? "",
+    job_start_date: initial?.job_start_date ?? "",
+    work_month_start_day:
+      initial?.work_month_start_day != null ? String(initial.work_month_start_day) : "",
+    contract_value: initial?.contract_value != null ? String(initial.contract_value) : "",
+    work_hours: initial?.work_hours != null ? String(initial.work_hours) : "",
+    hours_per_week: initial?.hours_per_week != null ? String(initial.hours_per_week) : "",
+    wages_hours_per_day:
+      initial?.wages_hours_per_day != null ? String(initial.wages_hours_per_day) : "",
+    latitude: initial?.latitude != null ? String(initial.latitude) : "",
+    longitude: initial?.longitude != null ? String(initial.longitude) : "",
+  };
+}
+```
+
+- [ ] **Step 6: Typecheck**
+
+Run: `npm run typecheck`
+Expected: no errors.
+
+- [ ] **Step 7: Set it for the one real site**
+
+Not a code step — a reminder for whoever runs this plan: after deploying, open the Sites page, edit "The Hills ext 12," and fill in both **Job start date** and (if its work month doesn't run 1st–30th) **Work month starts on day**. Until `job_start_date` is set, every sheet will show "—" instead of a Month/Week badge for that site's rows.
+
+- [ ] **Step 8: Commit**
+
+```bash
+git add src/components/site-form-dialog.tsx
+git commit -m "feat(sites): add work-month-start-day field to the site form"
+```
+
+---
+
+### Task 6: Timesheets
+
+**Files:**
+- Modify: `src/app/dashboard/workforce/timesheets/page.tsx`
+- Modify: `src/app/dashboard/workforce/timesheets/timesheets-view.tsx`
+
+- [ ] **Step 1: Attach `projectPeriod` in the loader**
+
+In `src/app/dashboard/workforce/timesheets/page.tsx`, add the import and compute `now` once, then attach the field in the `rows` map:
+
+```typescript
+import Link from "next/link";
+import { ClipboardList } from "lucide-react";
+import { pbAdmin } from "@/lib/pb";
+import { Topbar } from "@/components/layout/sidebar";
+import { Button } from "@/components/ui/button";
+import { ImportTimesheetsButton } from "@/components/import-timesheets-button";
+import { deriveProjectPeriodLabel } from "@/lib/project-calendar";
+import { TimesheetsView, type TimesheetEntryRow } from "./timesheets-view";
+```
+
+In the loader body, right after `const docStatusById = new Map(...)`, add:
+
+```typescript
+  const now = new Date();
+```
+
+Then in the `rows` map, add `projectPeriod` to the returned object:
+
+```typescript
+  const rows: TimesheetEntryRow[] = entries.map((e) => {
+    const emp = (e.expand?.employee ??
+      employeeById.get(e.employee)) as { name?: string; employee_no?: string } | undefined;
+    const site = (e.expand?.site ?? siteById.get(e.site)) as
+      | { name?: string; project_code?: string }
+      | undefined;
+    const timesheetId = e.expand?.timesheet?.id ?? (e.timesheet ?? "");
+    const siteRecord = siteById.get(e.site);
+    return {
+      id: e.id,
+      employeeId: e.employee ?? "",
+      employeeName: emp?.name ?? "(unknown)",
+      employeeNo: emp?.employee_no ?? "",
+      siteId: e.site ?? "",
+      siteName: site?.name ?? "(unknown)",
+      siteProjectCode: site?.project_code ?? "",
+      dateLogged: e.date_logged ?? "",
+      hoursWorked: e.hours_worked ?? 0,
+      hasDocument: !!timesheetId,
+      documentStatus: timesheetId ? docStatusById.get(timesheetId) ?? null : null,
+      projectPeriod: deriveProjectPeriodLabel(e.date_logged ?? "", siteRecord ?? {}, now),
+    };
+  });
+```
+
+- [ ] **Step 2: Add the field to `TimesheetEntryRow` and filter/display it**
+
+In `src/app/dashboard/workforce/timesheets/timesheets-view.tsx`:
+
+Add the import:
+
+```typescript
+import {
+  type ProjectPeriodFilterValue,
+  type ProjectPeriodLabel,
+  matchesProjectPeriodFilter,
+} from "@/lib/project-calendar";
+import { ProjectPeriodBadge } from "@/components/project-period-badge";
+```
+
+Add the field to the row interface:
+
+```typescript
+export interface TimesheetEntryRow {
+  id: string;
+  employeeId: string;
+  employeeName: string;
+  employeeNo: string;
+  siteId: string;
+  siteName: string;
+  siteProjectCode: string;
+  /** ISO date string (YYYY-MM-DD). */
+  dateLogged: string;
+  hoursWorked: number;
+  /** True when the row was created from a spreadsheet upload. */
+  hasDocument: boolean;
+  /** Document status from the source upload, if any. */
+  documentStatus?: string | null;
+  projectPeriod: ProjectPeriodLabel | null;
+}
+```
+
+Add filter state (next to `sourceFilter`):
+
+```typescript
+  const [periodFilter, setPeriodFilter] = React.useState<ProjectPeriodFilterValue>("all");
+```
+
+Add it to the filter predicate:
+
+```typescript
+  const filtered = React.useMemo(() => {
+    const q = search.trim().toLowerCase();
+    return rows.filter((r) => {
+      if (siteFilter !== "all" && r.siteId !== siteFilter) return false;
+      if (sourceFilter === "uploaded" && !r.hasDocument) return false;
+      if (sourceFilter === "direct" && r.hasDocument) return false;
+      if (!matchesProjectPeriodFilter(periodFilter, r.projectPeriod)) return false;
+      if (q) {
+        const hay = `${r.employeeName} ${r.employeeNo}`.toLowerCase();
+        if (!hay.includes(q)) return false;
+      }
+      return true;
+    });
+  }, [rows, siteFilter, sourceFilter, periodFilter, search]);
+```
+
+Add it to the page-reset effect and the `filtersActive`/reset-button logic:
+
+```typescript
+  React.useEffect(() => {
+    setPage(1);
+  }, [siteFilter, sourceFilter, periodFilter, search]);
+
+  const filtersActive =
+    siteFilter !== "all" || sourceFilter !== "all" || periodFilter !== "all" || search !== "";
+```
+
+```typescript
+          {filtersActive && (
+            <Button
+              variant="ghost"
+              size="sm"
+              onClick={() => {
+                setSiteFilter("all");
+                setSourceFilter("all");
+                setPeriodFilter("all");
+                setSearch("");
+              }}
+            >
+              Reset
+            </Button>
+          )}
+```
+
+Add the filter control, right after the "Source" `SelectFilter`:
+
+```tsx
+          <SelectFilter
+            label="Period"
+            value={periodFilter}
+            onChange={(v) => setPeriodFilter(v as ProjectPeriodFilterValue)}
+            options={[
+              { value: "all", label: "All time" },
+              { value: "today", label: "Today" },
+              { value: "week", label: "This week" },
+              { value: "month", label: "This month" },
+            ]}
+          />
+```
+
+Add the badge column to the table. Header:
+
+```tsx
+                <TableRow>
+                  <TableHead>Date</TableHead>
+                  <TableHead>Worker</TableHead>
+                  <TableHead>Site</TableHead>
+                  <TableHead>Month/Week</TableHead>
+                  <TableHead className="text-right">Hours</TableHead>
+                  <TableHead>Source</TableHead>
+                </TableRow>
+```
+
+Body — add one `<TableCell>` after the Site cell:
+
+```tsx
+                    <TableCell>
+                      <div className="flex items-center gap-1">
+                        <span className="text-sm">{r.siteName}</span>
+                        {r.siteProjectCode && (
+                          <Badge variant="outline" className="font-mono text-[10px]">
+                            {r.siteProjectCode}
+                          </Badge>
+                        )}
+                      </div>
+                    </TableCell>
+                    <TableCell>
+                      <ProjectPeriodBadge period={r.projectPeriod} />
+                    </TableCell>
+```
+
+- [ ] **Step 3: Typecheck**
+
+Run: `npm run typecheck`
+Expected: no errors.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add src/app/dashboard/workforce/timesheets/page.tsx src/app/dashboard/workforce/timesheets/timesheets-view.tsx
+git commit -m "feat(timesheets): add project Month/Week badge and filter"
+```
+
+---
+
+### Task 7: Delivery Notes
+
+**Files:**
+- Modify: `src/app/dashboard/financial/delivery-notes/page.tsx`
+- Modify: `src/app/dashboard/financial/delivery-notes/delivery-notes-view.tsx`
+
+- [ ] **Step 1: Attach `projectPeriod` in the loader**
+
+In `src/app/dashboard/financial/delivery-notes/page.tsx`, add the import:
+
+```typescript
+import { deriveProjectPeriodLabel } from "@/lib/project-calendar";
+```
+
+Right after `const siteById = new Map(...)`, add:
+
+```typescript
+  const now = new Date();
+```
+
+In the `rows` map, add `projectPeriod`:
+
+```typescript
+  const rows: DeliveryNoteRow[] = dns.map((d) => {
+    const site =
+      (d.expand?.site as { name?: string; project_code?: string } | undefined) ??
+      siteById.get(d.site);
+    const poId =
+      (d.expand?.purchase_order as { id?: string } | undefined)?.id ??
+      (d.purchase_order ?? "");
+    const itemAgg = itemsByDn.get(d.id) ?? { count: 0, total: 0 };
+    return {
+      id: d.id,
+      deliveryNoteNumber: d.delivery_note_number ?? "",
+      siteId: d.site ?? "",
+      siteName: site?.name ?? "(unknown)",
+      siteProjectCode: site?.project_code ?? "",
+      purchaseOrderId: poId,
+      purchaseOrderNumber: poId ? poById.get(poId) ?? "" : "",
+      dateReceived: d.date_received ?? "",
+      receivedByName: d.received_by_name ?? d.received_by ?? "",
+      processingStatus: d.processing_status ?? "",
+      isVerified: !!d.is_verified,
+      ocrConfidence: d.ocr_confidence ?? null,
+      slipImage: d.slip_image ?? "",
+      itemCount: itemAgg.count,
+      totalReceived: itemAgg.total,
+      projectPeriod: deriveProjectPeriodLabel(
+        d.date_received ?? "",
+        siteById.get(d.site) ?? {},
+        now,
+      ),
+    };
+  });
+```
+
+- [ ] **Step 2: Add the field to `DeliveryNoteRow` and filter/display it**
+
+In `src/app/dashboard/financial/delivery-notes/delivery-notes-view.tsx`:
+
+Add the import:
+
+```typescript
+import {
+  type ProjectPeriodFilterValue,
+  type ProjectPeriodLabel,
+  matchesProjectPeriodFilter,
+} from "@/lib/project-calendar";
+import { ProjectPeriodBadge } from "@/components/project-period-badge";
+```
+
+Add the field:
+
+```typescript
+export interface DeliveryNoteRow {
+  id: string;
+  deliveryNoteNumber: string;
+  siteId: string;
+  siteName: string;
+  siteProjectCode: string;
+  purchaseOrderId: string;
+  purchaseOrderNumber: string;
+  dateReceived: string;
+  receivedByName: string;
+  processingStatus: string;
+  isVerified: boolean;
+  ocrConfidence: number | null;
+  slipImage: string;
+  itemCount: number;
+  totalReceived: number;
+  projectPeriod: ProjectPeriodLabel | null;
+}
+```
+
+Add filter state:
+
+```typescript
+  const [periodFilter, setPeriodFilter] = React.useState<ProjectPeriodFilterValue>("all");
+```
+
+Add it to the filter predicate:
+
+```typescript
+  const filtered = React.useMemo(() => {
+    const q = search.trim().toLowerCase();
+    return rows.filter((r) => {
+      if (siteFilter !== "all" && r.siteId !== siteFilter) return false;
+      if (statusFilter !== "all") {
+        if (statusFilter === "manually-verified") {
+          if (!r.isVerified) return false;
+        } else if (r.processingStatus !== statusFilter) {
+          return false;
+        }
+      }
+      if (!matchesProjectPeriodFilter(periodFilter, r.projectPeriod)) return false;
+      if (q) {
+        const hay = `${r.deliveryNoteNumber} ${r.purchaseOrderNumber}`.toLowerCase();
+        if (!hay.includes(q)) return false;
+      }
+      return true;
+    });
+  }, [rows, siteFilter, statusFilter, periodFilter, search]);
+```
+
+Reset effect and `filtersActive`:
+
+```typescript
+  React.useEffect(() => {
+    setPage(1);
+  }, [siteFilter, statusFilter, periodFilter, search]);
+```
+
+```typescript
+  const filtersActive =
+    siteFilter !== "all" || statusFilter !== "all" || periodFilter !== "all" || search !== "";
+```
+
+Reset button handler:
+
+```typescript
+          {filtersActive && (
+            <Button
+              variant="ghost"
+              size="sm"
+              onClick={() => {
+                setSiteFilter("all");
+                setStatusFilter("all");
+                setPeriodFilter("all");
+                setSearch("");
+              }}
+            >
+              Reset
+            </Button>
+          )}
+```
+
+Filter control, right after the "Status" `SelectFilter`:
+
+```tsx
+          <SelectFilter
+            label="Period"
+            value={periodFilter}
+            onChange={(v) => setPeriodFilter(v as ProjectPeriodFilterValue)}
+            options={[
+              { value: "all", label: "All time" },
+              { value: "today", label: "Today" },
+              { value: "week", label: "This week" },
+              { value: "month", label: "This month" },
+            ]}
+          />
+```
+
+Table header — add a column after "Site":
+
+```tsx
+                <TableRow>
+                  <TableHead>Date</TableHead>
+                  <TableHead>DN #</TableHead>
+                  <TableHead>PO #</TableHead>
+                  <TableHead>Site</TableHead>
+                  <TableHead>Month/Week</TableHead>
+                  <TableHead className="text-right">Lines</TableHead>
+                  <TableHead className="text-right">Qty</TableHead>
+                  <TableHead>Status</TableHead>
+                  <TableHead className="w-[60px]" />
+                </TableRow>
+```
+
+Table body — add the cell after the Site cell:
+
+```tsx
+                    <TableCell>
+                      <div className="flex items-center gap-1">
+                        <span className="text-sm">{r.siteName}</span>
+                        {r.siteProjectCode && (
+                          <Badge variant="outline" className="font-mono text-[10px]">
+                            {r.siteProjectCode}
+                          </Badge>
+                        )}
+                      </div>
+                    </TableCell>
+                    <TableCell>
+                      <ProjectPeriodBadge period={r.projectPeriod} />
+                    </TableCell>
+```
+
+- [ ] **Step 3: Typecheck**
+
+Run: `npm run typecheck`
+Expected: no errors.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add src/app/dashboard/financial/delivery-notes/page.tsx src/app/dashboard/financial/delivery-notes/delivery-notes-view.tsx
+git commit -m "feat(delivery-notes): add project Month/Week badge and filter"
+```
+
+---
+
+### Task 8: Purchase Orders
+
+Unlike the other three sheets, `PoRow` doesn't currently carry a raw `siteId` or upload date at all (only the derived `projectCode`/`projectName`, and `requiredByDate` which is a different date than when the PO was uploaded) — those two fields need adding first. This page also renders as a card list (`<ul><li>`), not a `<Table>`, so the badge goes on the card, not in a table cell.
+
+**Files:**
+- Modify: `src/app/dashboard/financial/purchase-orders/page.tsx`
+- Modify: `src/app/dashboard/financial/purchase-orders/purchasing-view.tsx`
+
+- [ ] **Step 1: Add `siteId`/`dateUploaded`, build a site lookup, attach `projectPeriod`**
+
+In `src/app/dashboard/financial/purchase-orders/page.tsx`, add the import:
+
+```typescript
+import { deriveProjectPeriodLabel } from "@/lib/project-calendar";
+```
+
+Right after `const dnsByPo = new Map(...)` block, add a site lookup (this page doesn't build one today):
+
+```typescript
+  const siteById = new Map(sites.map((s) => [s.id, s]));
+  const now = new Date();
+```
+
+In the `rows` map, add `siteId`, `dateUploaded`, and `projectPeriod` to the returned object:
+
+```typescript
+      return {
+        id: p.id,
+        poNumber: p.purchase_order_number,
+        supplier: p.supplier,
+        supplierRefId: p.supplier_ref ?? null,
+        supplierRefName: supplierRef?.name ?? null,
+        projectCode,
+        projectName: site?.name ?? projectCode,
+        siteId: p.site ?? "",
+        dateUploaded: p.date_uploaded ?? "",
+        requiredByDate: p.required_by_date,
+        orderedBy: p.ordered_by,
+        isVerified: !!p.is_verified,
+        totalValue: p.total_value,
+        itemCount: its.length,
+        deliveryNoteCount: dnsForPo.length,
+        deliveryNoteVerified: dnsForPo.filter((d) => d.is_verified).length,
+        pendingDnCount,
+        fulfillmentPct,
+        totalOrdered: ord,
+        totalReceived: rcv,
+        projectPeriod: deriveProjectPeriodLabel(
+          p.date_uploaded ?? "",
+          siteById.get(p.site) ?? {},
+          now,
+        ),
+      };
+```
+
+- [ ] **Step 2: Add the fields to `PoRow`, filter, and render the badge**
+
+In `src/app/dashboard/financial/purchase-orders/purchasing-view.tsx`:
+
+Add the import:
+
+```typescript
+import {
+  type ProjectPeriodFilterValue,
+  type ProjectPeriodLabel,
+  matchesProjectPeriodFilter,
+} from "@/lib/project-calendar";
+import { ProjectPeriodBadge } from "@/components/project-period-badge";
+```
+
+Add the fields to `PoRow`:
+
+```typescript
+export interface PoRow {
+  id: string;
+  poNumber: string;
+  projectCode: string;
+  projectName: string;
+  siteId: string;
+  /** ISO date string (YYYY-MM-DD) — when the PO document was uploaded. */
+  dateUploaded: string;
+  supplier: string;
+  /** Resolved supplier record id, if a match was made at upload or later. */
+  supplierRefId: string | null;
+  /** Display name of the linked supplier (mirrors supplierRefId's record). */
+  supplierRefName: string | null;
+  requiredByDate: string;
+  orderedBy: string;
+  totalValue: number;
+  isVerified: boolean;
+  itemCount: number;
+  deliveryNoteCount: number;
+  deliveryNoteVerified: number;
+  pendingDnCount: number;
+  fulfillmentPct: number;
+  totalOrdered: number;
+  totalReceived: number;
+  projectPeriod: ProjectPeriodLabel | null;
+}
+```
+
+Add filter state, next to `statusFilter`:
+
+```typescript
+  const [periodFilter, setPeriodFilter] = React.useState<ProjectPeriodFilterValue>("all");
+```
+
+Add it to the filter predicate:
+
+```typescript
+  const filtered = React.useMemo(() => {
+    const q = search.trim().toLowerCase();
+    return rows.filter((r) => {
+      if (projectFilter !== "all" && r.projectCode !== projectFilter) return false;
+      if (statusFilter === "verified" && !r.isVerified) return false;
+      if (statusFilter === "unverified" && r.isVerified) return false;
+      if (statusFilter === "fulfilled" && r.fulfillmentPct < 100) return false;
+      if (statusFilter === "open" && r.fulfillmentPct >= 100) return false;
+      if (!matchesProjectPeriodFilter(periodFilter, r.projectPeriod)) return false;
+      if (q) {
+        const hay = `${r.poNumber} ${r.supplier} ${r.projectCode}`.toLowerCase();
+        if (!hay.includes(q)) return false;
+      }
+      return true;
+    });
+  }, [rows, projectFilter, statusFilter, periodFilter, search]);
+```
+
+Reset effect and `filtersActive`:
+
+```typescript
+  React.useEffect(() => {
+    setPage(1);
+  }, [projectFilter, statusFilter, periodFilter, search]);
+```
+
+```typescript
+  const filtersActive =
+    projectFilter !== "all" || statusFilter !== "all" || periodFilter !== "all" || search !== "";
+```
+
+Reset button handler:
+
+```typescript
+          {filtersActive && (
+            <Button
+              variant="ghost"
+              size="sm"
+              onClick={() => {
+                setProjectFilter("all");
+                setStatusFilter("all");
+                setPeriodFilter("all");
+                setSearch("");
+              }}
+            >
+              Reset
+            </Button>
+          )}
+```
+
+Filter control — this file uses a raw `<Select>`, not the `SelectFilter` wrapper (there isn't one in this file). Add it right after the status `<Select>` block:
+
+```tsx
+          <Select
+            value={periodFilter}
+            onValueChange={(v) => setPeriodFilter(v as ProjectPeriodFilterValue)}
+          >
+            <SelectTrigger className="w-[160px]">
+              <SelectValue />
+            </SelectTrigger>
+            <SelectContent>
+              <SelectItem value="all">All time</SelectItem>
+              <SelectItem value="today">Today</SelectItem>
+              <SelectItem value="week">This week</SelectItem>
+              <SelectItem value="month">This month</SelectItem>
+            </SelectContent>
+          </Select>
+```
+
+Render the badge on the PO card. In `PoListItem`, add it next to the project-code badge:
+
+```tsx
+            <Badge variant="outline" className="font-mono text-xs">
+              {po.projectCode || "—"}
+            </Badge>
+            <ProjectPeriodBadge period={po.projectPeriod} />
+```
+
+- [ ] **Step 3: Typecheck**
+
+Run: `npm run typecheck`
+Expected: no errors.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add src/app/dashboard/financial/purchase-orders/page.tsx src/app/dashboard/financial/purchase-orders/purchasing-view.tsx
+git commit -m "feat(purchase-orders): add project Month/Week badge and filter"
+```
+
+---
+
+### Task 9: Fuel Logs
+
+**Files:**
+- Modify: `src/app/dashboard/plant/fuel-logs/page.tsx`
+- Modify: `src/app/dashboard/plant/fuel-logs/fuel-logs-view.tsx`
+
+- [ ] **Step 1: Attach `projectPeriod` in the loader**
+
+In `src/app/dashboard/plant/fuel-logs/page.tsx`, add the import:
+
+```typescript
+import { deriveProjectPeriodLabel } from "@/lib/project-calendar";
+```
+
+Right after `const fuelPrices = await loadFuelPrices();`, add:
+
+```typescript
+  const now = new Date();
+```
+
+In the `rows` map, add `projectPeriod`:
+
+```typescript
+    return {
+      id: l.id,
+      dateLogged: l.date_logged ?? "",
+      vehicleId: l.vehicle ?? "",
+      vehicleDescription: v?.description ?? "(unknown)",
+      unitType:
+        v?.unit_type === "plant" ? "plant" : "fuel",
+      siteId: l.site ?? "",
+      siteName: site?.name ?? "(unknown)",
+      siteProjectCode: site?.project_code ?? "",
+      litres: l.litres ?? 0,
+      odoReading: l.odo_reading ?? null,
+      cost: (l.litres ?? 0) * resolveFuelPrice(l.date_logged, fuelPrices),
+      latestConsumption:
+        "latest_consumption" in l
+          ? ((l as { latest_consumption?: number }).latest_consumption ?? null)
+          : null,
+      hasDocument: !!fuelSheetId,
+      documentStatus: fuelSheetId
+        ? docStatusById.get(fuelSheetId) ?? null
+        : null,
+      projectPeriod: deriveProjectPeriodLabel(
+        l.date_logged ?? "",
+        siteById.get(l.site) ?? {},
+        now,
+      ),
+    };
+```
+
+- [ ] **Step 2: Add the field to `FuelLogRow` and filter/display it**
+
+In `src/app/dashboard/plant/fuel-logs/fuel-logs-view.tsx`:
+
+Add the import:
+
+```typescript
+import {
+  type ProjectPeriodFilterValue,
+  type ProjectPeriodLabel,
+  matchesProjectPeriodFilter,
+} from "@/lib/project-calendar";
+import { ProjectPeriodBadge } from "@/components/project-period-badge";
+```
+
+Add the field:
+
+```typescript
+export interface FuelLogRow {
+  id: string;
+  dateLogged: string;
+  vehicleId: string;
+  vehicleDescription: string;
+  unitType: "fuel" | "plant";
+  siteId: string;
+  siteName: string;
+  siteProjectCode: string;
+  litres: number;
+  odoReading: number | null;
+  cost: number;
+  latestConsumption: number | null;
+  hasDocument: boolean;
+  documentStatus?: string | null;
+  projectPeriod: ProjectPeriodLabel | null;
+}
+```
+
+Add filter state, next to `sourceFilter`:
+
+```typescript
+  const [periodFilter, setPeriodFilter] = React.useState<ProjectPeriodFilterValue>("all");
+```
+
+Add it to the filter predicate:
+
+```typescript
+  const filtered = React.useMemo(() => {
+    const q = search.trim().toLowerCase();
+    return rows.filter((r) => {
+      if (siteFilter !== "all" && r.siteId !== siteFilter) return false;
+      if (unitFilter !== "all" && r.unitType !== unitFilter) return false;
+      if (sourceFilter === "uploaded" && !r.hasDocument) return false;
+      if (sourceFilter === "direct" && r.hasDocument) return false;
+      if (!matchesProjectPeriodFilter(periodFilter, r.projectPeriod)) return false;
+      if (q) {
+        const hay = `${r.vehicleDescription}`.toLowerCase();
+        if (!hay.includes(q)) return false;
+      }
+      return true;
+    });
+  }, [rows, siteFilter, unitFilter, sourceFilter, periodFilter, search]);
+```
+
+Reset effect and `filtersActive`:
+
+```typescript
+  React.useEffect(() => {
+    setPage(1);
+  }, [siteFilter, unitFilter, sourceFilter, periodFilter, search]);
+```
+
+```typescript
+  const filtersActive =
+    siteFilter !== "all" || unitFilter !== "all" || sourceFilter !== "all" || periodFilter !== "all" || search !== "";
+```
+
+Reset button handler:
+
+```typescript
+          {filtersActive && (
+            <Button
+              variant="ghost"
+              size="sm"
+              onClick={() => {
+                setSiteFilter("all");
+                setUnitFilter("all");
+                setSourceFilter("all");
+                setPeriodFilter("all");
+                setSearch("");
+              }}
+            >
+              Reset
+            </Button>
+          )}
+```
+
+Filter control, right after the "Source" `SelectFilter`:
+
+```tsx
+          <SelectFilter
+            label="Period"
+            value={periodFilter}
+            onChange={(v) => setPeriodFilter(v as ProjectPeriodFilterValue)}
+            options={[
+              { value: "all", label: "All time" },
+              { value: "today", label: "Today" },
+              { value: "week", label: "This week" },
+              { value: "month", label: "This month" },
+            ]}
+          />
+```
+
+Table header — add a column after "Site":
+
+```tsx
+                <TableRow>
+                  <TableHead>Date</TableHead>
+                  <TableHead>Vehicle / equipment</TableHead>
+                  <TableHead>Site</TableHead>
+                  <TableHead>Month/Week</TableHead>
+                  <TableHead className="text-right">Litres</TableHead>
+                  <TableHead className="text-right">Reading</TableHead>
+                  <TableHead className="text-right">Cost</TableHead>
+                  <TableHead>Source</TableHead>
+                </TableRow>
+```
+
+Table body — add the cell after the Site cell:
+
+```tsx
+                    <TableCell>
+                      <div className="flex items-center gap-1">
+                        <span className="text-sm">{r.siteName}</span>
+                        {r.siteProjectCode && (
+                          <Badge variant="outline" className="font-mono text-[10px]">
+                            {r.siteProjectCode}
+                          </Badge>
+                        )}
+                      </div>
+                    </TableCell>
+                    <TableCell>
+                      <ProjectPeriodBadge period={r.projectPeriod} />
+                    </TableCell>
+```
+
+- [ ] **Step 3: Typecheck**
+
+Run: `npm run typecheck`
+Expected: no errors.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add src/app/dashboard/plant/fuel-logs/page.tsx src/app/dashboard/plant/fuel-logs/fuel-logs-view.tsx
+git commit -m "feat(fuel-logs): add project Month/Week badge and filter"
+```
+
+---
+
+### Task 10: Full verification pass
+
+**Files:** none (verification only)
+
+- [ ] **Step 1: Typecheck the whole project**
+
+Run: `npm run typecheck`
+Expected: 0 errors.
+
+- [ ] **Step 2: Run the full test suite**
+
+Run: `npm run test:run`
+Expected: all tests pass, including the new `project-calendar.test.ts`.
+
+- [ ] **Step 3: Manual check (not automatable)**
+
+Per the design decisions above, confirm by hand:
+- Edit the one real site ("The Hills ext 12") and set a Job start date (and a Work month start day if it isn't the 1st). Confirm the four sheets start showing "M1 · W1"-style badges for that site's rows instead of "—".
+- On each of the four pages, confirm the Period filter narrows to the expected rows for Today / This week / This month, and "All time" shows everything again.
+- Confirm a row from BEFORE the site's job start date still renders "—" (out of range) rather than a negative or zero month number.
+
+- [ ] **Step 4: Commit any fixes found during verification**
+
+```bash
+git add -A
+git commit -m "fix(project-calendar): address verification findings"
+```
+
+(Skip this step entirely if nothing needed fixing.)
+
+---
+
+## Self-Review
+
+**Spec coverage:**
+- Custom per-site work-month start day, not just calendar months → Tasks 1, 2 ✅
+- Day-of-month overflow clamps to the last real day → Task 2 (`clampDay`, tested against Feb) ✅
+- Weeks are simple 7-day blocks from the cycle start, capped at 4 → Task 2 (tested) ✅
+- Every row on Timesheets/Delivery Notes/Purchase Orders/Fuel Logs shows its Month/Week → Tasks 6–9 ✅
+- Today/This week/This month/All time filter on all four → Tasks 6–9 ✅
+- Setting the start day + start date happens on the site edit page → Task 5 ✅
+- Vehicles/Equipment explicitly out of scope → not touched anywhere in this plan ✅
+
+**Placeholder scan:** none found — every step has complete code or an exact command with expected output. The one non-code step (Task 5 Step 7) is explicitly marked as a manual reminder, not a coding task, and says exactly what to do.
+
+**Type consistency:** `ProjectPeriod`, `ProjectPeriodLabel`, `ProjectPeriodSite`, and `ProjectPeriodFilterValue` are defined once in `project-calendar.ts` (Task 2) and imported by that exact name everywhere else (Tasks 3, 6–9) — no renamed variants. `deriveProjectPeriodLabel`'s signature (`dateISO, site, now?`) is called identically in all four loaders. `matchesProjectPeriodFilter`'s signature (`filter, period`) is called identically in all four views.
+
+---
+
+## Execution Choice
+
+Plan complete and saved to `docs/superpowers/plans/2026-09-11-project-month-week.md`. Two execution options:
+
+1. **Subagent-Driven (recommended)** — I dispatch a fresh subagent per task, review between tasks, fast iteration.
+2. **Inline Execution** — Execute tasks in this session using executing-plans, batch execution with checkpoints.
+
+Which approach? (Or hand it to your MiniMax agent, same as the last few — I'll review the diff afterward.)
diff --git a/scripts/migrations/2026-09-11-add-site-work-month-field.py b/scripts/migrations/2026-09-11-add-site-work-month-field.py
index a752b21..bbb247c 100644
--- a/scripts/migrations/2026-09-11-add-site-work-month-field.py
+++ b/scripts/migrations/2026-09-11-add-site-work-month-field.py
@@ -8,7 +8,7 @@ One-shot PocketBase migration applied via:
   python3 scripts/migrations/2026-09-11-add-site-work-month-field.py
 
 Adds sites.work_month_start_day (see
-docs/superpowers/specs/2026-09-11-project-month-week-design.md for why:
+docs/superpowers/plans/2026-09-11-project-month-week.md for why:
 some sites' "work months" don't run 1st-30th, they run e.g. 21st-21st).
 
 Strictly additive, and the field is not required — existing sites keep