Team project on inherited broken codebase

"""make_inherited_repo.py - run once, then never edit. Writes delay-predictor/ and p5_sealed/.

You are taking over a half-finished 'delivery delay predictor' from an intern who has
left. This script builds that repo exactly as he left it: the shipment file, his source
files, his README, his handover note, and his git history including the commit where he
added credentials and the later one where he 'removed' them. Seeded, so every team in
the batch inherits the identical mess.

Standard library only - no pandas, no network, no model. The REPO it writes needs pandas
and scikit-learn; that is the intern's problem, and soon yours.
"""
import csv
import json
import os
import random
import subprocess
import sys
from datetime import datetime, timedelta
from pathlib import Path

RNG = random.Random(20260420)
REPO = Path("delay-predictor")
SEALED = Path("p5_sealed")
N_ROWS = 18000
START = datetime(2024, 9, 1, 6, 0)
END = datetime(2026, 3, 31, 22, 0)
REGIME = datetime(2025, 11, 15)        # the week GatiRoad fell apart
COURIERS = ["Shreeji-Surface", "GatiRoad", "NexusExpress", "Bhiwandi-Direct", "IndiaPost-Cargo"]
HUBS = ["Bhiwandi-A", "Bhiwandi-B", "Nashik-Feeder"]
DEST = [("Mumbai", 1), ("Pune", 1), ("Surat", 1), ("Nagpur", 2), ("Indore", 2),
        ("Aurangabad", 2), ("Kolhapur", 2), ("Jalgaon", 3), ("Ratnagiri", 3),
        ("Bhusawal", 3), ("Latur", 3), ("Gondia", 3), ("Bhilai", 3), ("Cuttack", 3)]
DIST = {"Mumbai": 45, "Pune": 160, "Surat": 280, "Nagpur": 720, "Indore": 590,
        "Aurangabad": 310, "Kolhapur": 400, "Jalgaon": 380, "Ratnagiri": 330,
        "Bhusawal": 420, "Latur": 470, "Gondia": 890, "Bhilai": 1080, "Cuttack": 1580}
COURIER_RISK = {"NexusExpress": -0.75, "Shreeji-Surface": -0.35, "Bhiwandi-Direct": 0.0,
                "GatiRoad": 0.25, "IndiaPost-Cargo": 1.00}

# --------------------------------------------------------------------------- the SLA rule
# This exact text becomes src/sla.py. The generator imports it to build promised_ts, so
# the function IS the ground truth of this world. It is unreadable and it is correct.
SLA_SRC = '''"""ops sheet v3. do not touch without asking ops. -gp"""


def calc(a, b, c, d):
    if b == "express":
        if a == 1:
            h = 12 if c < 60 else (24 if c < 150 else (36 if c < 600 else 48))
        elif a == 2:
            h = 18 if c < 60 else (36 if c < 150 else (48 if c < 600 else 60))
        else:
            h = 24 if c < 60 else (48 if c < 150 else (60 if c < 600 else 72))
    else:
        if a == 1:
            h = 24 if c < 60 else (48 if c < 150 else (72 if c < 600 else 96))
        elif a == 2:
            h = 30 if c < 60 else (60 if c < 150 else (84 if c < 600 else 108))
        else:
            h = 36 if c < 60 else (72 if c < 150 else (96 if c < 600 else 120))
    if d in (6, 7, 8, 9):
        if a == 3:
            h = h + 12
    if d in (10, 11):
        if b == "standard":
            h = h + 24
    if c > 1400:
        h = h + 24
    return h
'''
_ns = {}
exec(SLA_SRC, _ns)
calc = _ns["calc"]

# --------------------------------------------------------------------------- the shipments
rows = []
span = int((END - START).total_seconds())
stamps = sorted(START + timedelta(seconds=RNG.randint(0, span)) for _ in range(N_ROWS))
for n, pickup in enumerate(stamps, 1):
    city, tier = RNG.choice(DEST)
    dist = DIST[city] + RNG.randint(-25, 25)
    service = RNG.choices(["express", "standard"], weights=[38, 62])[0]
    weight = round(RNG.choices([RNG.uniform(0.2, 3), RNG.uniform(3, 18), RNG.uniform(18, 60)],
                               weights=[52, 36, 12])[0], 2)
    items = RNG.choices([1, 2, 3, 5], weights=[62, 22, 11, 5])[0]
    pay = RNG.choices(["cod", "prepaid"], weights=[58, 42])[0]
    courier = RNG.choice(COURIERS)
    hub = RNG.choice(HUBS)
    monsoon = 1 if pickup.month in (6, 7, 8, 9) else 0
    backlog = RNG.randint(40, 260) + (90 if monsoon else 0) + (140 if pickup.month in (10, 11) else 0)
    promised_hours = calc(tier, service, dist, pickup.month)

    # the real, learnable signal - honest, and nothing like 0.94 accuracy
    z = -3.70 + COURIER_RISK[courier]
    z += 0.55 * (tier - 1)
    z += 0.00095 * dist
    z += 0.0042 * (backlog - 150)
    z += 0.45 * monsoon
    z += 0.60 if pickup.month in (10, 11) else 0.0
    z += 0.30 if pay == "cod" else 0.0
    z += 0.38 if service == "express" else 0.0
    z += 0.28 if weight > 25 else 0.0
    z += 0.32 if pickup.hour >= 18 else 0.0
    z += 0.55 if (tier == 3 and monsoon) else 0.0
    if pickup >= REGIME and courier == "GatiRoad":
        z += 2.60                       # the regime change a random split cannot see
    if pickup >= REGIME and tier == 3:
        z += 0.50
    z += RNG.gauss(0, 0.20)
    p = 1.0 / (1.0 + 2.718281828459045 ** (-z))
    late = 1 if RNG.random() < p else 0

    if late:
        transit = promised_hours * RNG.uniform(1.04, 1.85)
    else:
        transit = promised_hours * RNG.uniform(0.32, 0.96)
    transit = round(transit, 2)
    attempts = 1
    if late and pay == "cod":
        attempts = RNG.choices([1, 2, 3], weights=[30, 50, 20])[0]
    elif late:
        attempts = RNG.choices([1, 2], weights=[70, 30])[0]
    delivered = pickup + timedelta(hours=transit)
    rows.append(dict(
        shipment_id=f"BHW{n + 300000}", pickup_ts=pickup.isoformat(sep=" ", timespec="seconds"),
        promised_ts=(pickup + timedelta(hours=promised_hours)).isoformat(sep=" ", timespec="seconds"),
        delivered_ts=delivered.isoformat(sep=" ", timespec="seconds"),
        origin_hub=hub, dest_city=city, dest_tier=tier, courier=courier,
        service_level=service, distance_km=dist, weight_kg=weight, items=items,
        payment_mode=pay, monsoon=monsoon, hub_backlog=backlog,
        actual_transit_hours=transit, delivery_attempts=attempts, is_late=late))

# --------------------------------------------------------------------------- the source files
FILES = {}

FILES["config.py"] = '''# paths for the delay model. update if you move the folder.
DATA_PATH = "/Users/ganeshambekar/Desktop/delay_project/data/shipments.csv"
MODEL_PATH = "/Users/ganeshambekar/Desktop/delay_project/models/model.pkl"
RANDOM_STATE = 42
TEST_SIZE = 0.2
'''

FILES["requirements.txt"] = "pandas\nscikit-learn\njoblib\n"

FILES["src/__init__.py"] = ""

FILES["src/sla.py"] = SLA_SRC

FILES["src/load.py"] = '''import pandas as pd

from config import DATA_PATH


def load_shipments():
    df = pd.read_csv(DATA_PATH)
    df["pickup_ts"] = pd.to_datetime(df["pickup_ts"])
    df["promised_ts"] = pd.to_datetime(df["promised_ts"])
    df["delivered_ts"] = pd.to_datetime(df["delivered_ts"])
    return df
'''

FILES["src/features.py"] = '''import pandas as pd


def promised_window_hours(df):
    """how many hours we promised the customer"""
    out = []
    for i in range(len(df)):
        gap = df["promised_ts"].iloc[i] - df["pickup_ts"].iloc[i]
        out.append(gap.seconds / 3600.0)
    return out


def courier_late_rate(df):
    """share of this courier's shipments that ran late"""
    couriers = df["courier"].tolist()
    if "is_late" not in df.columns:
        return [0.5] * len(couriers)
    late = df["is_late"].tolist()
    rates = []
    for i in range(len(couriers)):
        hits = 0
        total = 0
        for j in range(len(couriers)):
            if couriers[j] == couriers[i]:
                total += 1
                hits += late[j]
        rates.append(hits / total)
    return rates


def build(df):
    df = df.copy()
    df["promised_window_hours"] = promised_window_hours(df)
    df["courier_late_rate"] = courier_late_rate(df)
    df["pickup_hour"] = df["pickup_ts"].dt.hour
    df["pickup_dow"] = df["pickup_ts"].dt.dayofweek
    df["pickup_month"] = df["pickup_ts"].dt.month
    return df
'''

FILES["src/prep.py"] = '''NUM_COLS = ["distance_km", "weight_kg", "items", "hub_backlog", "promised_window_hours",
            "courier_late_rate", "pickup_hour", "pickup_dow", "pickup_month",
            "actual_transit_hours", "delivery_attempts"]
CAT_COLS = ["dest_tier", "service_level", "payment_mode", "courier", "origin_hub"]


def scale(df, cols=None):
    df = df.copy()
    for c in (cols or NUM_COLS):
        m = df[c].mean()
        s = df[c].std(ddof=0)
        df[c] = (df[c] - m) / (s if s else 1.0)
    return df


def encode(df, cols=None):
    df = df.copy()
    for c in (cols or CAT_COLS):
        df[c] = df[c].astype("category").cat.codes
    return df


def prepare(df):
    df = scale(df)
    df = encode(df)
    return df[NUM_COLS + CAT_COLS]
'''

FILES["src/train.py"] = '''import joblib
from sklearn.ensemble import RandomForestClassifier
from sklearn.metrics import accuracy_score, roc_auc_score
from sklearn.model_selection import train_test_split

from config import MODEL_PATH, RANDOM_STATE, TEST_SIZE
from src.features import build
from src.load import load_shipments
from src.prep import prepare


def main():
    df = load_shipments()
    df = build(df)
    X = prepare(df)
    y = df["is_late"]
    X_train, X_test, y_train, y_test = train_test_split(
        X, y, test_size=TEST_SIZE, random_state=RANDOM_STATE, shuffle=True)
    model = RandomForestClassifier(n_estimators=200, random_state=RANDOM_STATE, n_jobs=-1)
    model.fit(X_train, y_train)
    pred = model.predict(X_test)
    print("holdout accuracy :", round(accuracy_score(y_test, pred), 4))
    print("holdout roc auc  :", round(roc_auc_score(y_test, model.predict_proba(X_test)[:, 1]), 4))
    joblib.dump(model, MODEL_PATH)
    print("saved model to", MODEL_PATH)


if __name__ == "__main__":
    main()
'''

FILES["scripts/report.py"] = '''"""weekly model health report for the ops dashboard."""
import joblib
import pandas as pd

from config import MODEL_PATH
from src.features import build
from src.load import load_shipments
from src.prep import prepare


def main():
    df = build(load_shipments())
    X = prepare(df)
    model = joblib.load(MODEL_PATH)
    df["pred"] = model.predict(X)
    acc = (df["pred"] == df["is_late"]).mean()
    print("MODEL HEALTH THIS WEEK")
    print("rows scored :", len(df))
    print("accuracy    :", round(acc, 4))
    by_courier = df.groupby("courier").apply(
        lambda g: pd.Series({"n": len(g), "acc": (g["pred"] == g["is_late"]).mean()}))
    print(by_courier.to_markdown())


if __name__ == "__main__":
    main()
'''

FILES["src/serve.py"] = '''"""tiny scorer the ops dashboard calls. one shipment at a time."""
import joblib
import pandas as pd

from config import MODEL_PATH
from src.features import build
from src.prep import prepare


def load_and_predict(payload):
    model = joblib.load(MODEL_PATH)
    df = pd.DataFrame(payload if isinstance(payload, list) else [payload])
    df["pickup_ts"] = pd.to_datetime(df["pickup_ts"])
    df["promised_ts"] = pd.to_datetime(df["promised_ts"])
    df = build(df)
    X = prepare(df)
    return model.predict_proba(X)[:, 1].tolist()
'''

FILES["config/secrets.env"] = '''DB_URL=postgresql://delay_app:Bh1w4ndi%40Ship2025@10.20.4.11:5432/delaydb
MAPS_API_KEY=AIzaSyD-6f4kQpLm2nT8xVr0wZbYc3JhEuKvNqA
SLACK_WEBHOOK=https://hooks.slack.com/services/T02ABCD9/B04KLMN7/xY9qWs2ZpRtVu6Ha
'''

FILES[".gitignore"] = "config/secrets.env\n__pycache__/\n*.pkl\n.venv/\n"

FILES["README.md"] = '''# delay-predictor

Predicts whether a Bhiwandi outbound shipment will miss its promised delivery time.

## What it does
Reads the shipment dump, builds features, trains a random forest, saves the model.
The ops dashboard calls `src/serve.py` for a live probability.

## Results
**Accuracy 0.94 on held-out data.** Beats the old rule sheet by a wide margin.
Features used: distance, weight, city tier, courier, service level, hub backlog.

## Run it

    pip install -r requirements.txt
    python -m src.train
    python -m src.serve --port 8000
    python scripts/report.py --week last

## Tests

    pytest tests/

## Notes
Model is retrained every Monday morning by the cron on the ops box.
'''

FILES["HANDOVER.md"] = '''# Handover - Ganesh Ambekar, last working day 27 March 2026

Sorry this is short, I am joining the new place on Monday. Calling out what I remember.

1. The model is basically done. 0.94 accuracy, ops are happy with it. The only thing
   left is putting it behind a proper API.
2. `src/sla.py` is a mess, I wrote it in one night from the ops sheet. The tier logic in
   there is definitely wrong for tier 3, I never got around to rewriting it. Please
   rewrite that file first, it is the worst thing in the repo.
3. `src/prep.py` scaling caused a dashboard problem in February. I reverted it, then put
   it back because the real issue was somewhere else. It is fine now.
4. Data comes from the ops team every Monday as a CSV. Path is in `config.py`.
5. There are no tests yet. The code is small enough to check by eye.
6. `courier_late_rate` is the strongest feature. Do not remove it.
7. Credentials were in the repo at one point, I removed them in a later commit so we
   are clean now.
8. `promised_window_hours` sometimes prints small numbers for long routes. I think the
   CSV export is bad. Ask ops for a fresh dump.

Good luck. My personal email is on the git commits if something is really stuck,
but I will be busy for the first month.
'''

# --------------------------------------------------------------------------- write the repo
if REPO.exists():
    print(f"{REPO} already exists. Delete it first if you want a clean inheritance.")
    sys.exit(1)
(REPO / "data").mkdir(parents=True)
(REPO / "models").mkdir()
for rel, text in FILES.items():
    p = REPO / rel
    p.parent.mkdir(parents=True, exist_ok=True)
    p.write_text(text, encoding="utf-8")

with (REPO / "data/shipments.csv").open("w", newline="", encoding="utf-8") as fh:
    w = csv.DictWriter(fh, fieldnames=list(rows[0]))
    w.writeheader()
    w.writerows(rows)

# --------------------------------------------------------------------------- the git history
GP = "Ganesh Ambekar"
GE = "ganesh.ambekar.intern@example.com"


def git(*args, when=None):
    env = dict(os.environ, GIT_AUTHOR_NAME=GP, GIT_AUTHOR_EMAIL=GE,
               GIT_COMMITTER_NAME=GP, GIT_COMMITTER_EMAIL=GE)
    if when:
        env["GIT_AUTHOR_DATE"] = env["GIT_COMMITTER_DATE"] = when
    subprocess.run(["git", *args], cwd=REPO, env=env, check=True,
                   stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)


def commit(msg, paths, when, remove=()):
    for p in paths:
        git("add", "-f", p)
    for p in remove:
        git("rm", "--cached", "-q", p)
    git("commit", "-m", msg, when=when)


git("init", "-q", "-b", "main")
git("config", "user.name", GP)
git("config", "user.email", GE)

# earlier shapes of the two files whose history tells the story
PREP = FILES["src/prep.py"]
SCALE_FN = PREP[PREP.index("def scale("):PREP.index("def encode(")]
LEAK = ',\n            "actual_transit_hours", "delivery_attempts"]'
P_NOLEAK_NOSCALE = PREP.replace(LEAK, "]").replace("    df = scale(df)\n", "").replace(SCALE_FN, "")
P_LEAK_NOSCALE = PREP.replace("    df = scale(df)\n", "").replace(SCALE_FN, "")
P_LEAK_REVERT = PREP.replace("    df = scale(df)\n", "")
FEAT = FILES["src/features.py"]
CLR_FN = FEAT[FEAT.index("def courier_late_rate("):FEAT.index("def build(")]
F_NO_CLR = FEAT.replace(CLR_FN, "").replace(
    '    df["courier_late_rate"] = courier_late_rate(df)\n', "")
STAGES = {2: {"src/prep.py": P_NOLEAK_NOSCALE, "src/features.py": F_NO_CLR},
          4: {"src/prep.py": P_LEAK_NOSCALE},
          5: {"src/features.py": FEAT},
          6: {"src/prep.py": PREP},
          7: {"src/prep.py": P_LEAK_REVERT},
          8: {"src/prep.py": PREP}}

HIST = [
    ("first commit, shipment dump from ops", ["data/shipments.csv", "config.py"],
     "2026-01-09T19:40:00+05:30", ()),
    ("sla hours calc, matches the ops sheet exactly", ["src/__init__.py", "src/sla.py",
     "src/load.py"], "2026-01-14T21:05:00+05:30", ()),
    ("features + first model, 0.71 accuracy", ["src/features.py", "src/prep.py",
     "src/train.py"], "2026-01-21T23:15:00+05:30", ()),
    ("add db and maps config for the enrichment job", ["config/secrets.env"],
     "2026-01-28T18:20:00+05:30", ()),
    ("use transit hours as a feature, accuracy jumps to 0.94!!", ["src/prep.py"],
     "2026-02-03T22:50:00+05:30", ()),
    ("courier late rate feature", ["src/features.py"], "2026-02-11T20:30:00+05:30", ()),
    ("scale numeric cols before fit", ["src/prep.py"], "2026-02-18T21:10:00+05:30", ()),
    ("revert scaling, dashboard numbers went crazy", ["src/prep.py"],
     "2026-02-20T09:05:00+05:30", ()),
    ("put scaling back, dashboard issue was elsewhere", ["src/prep.py"],
     "2026-02-24T22:40:00+05:30", ()),
    ("remove creds from repo", [".gitignore"], "2026-03-02T11:30:00+05:30",
     ("config/secrets.env",)),
    ("weekly report script for ops", ["scripts/report.py"], "2026-03-09T20:15:00+05:30", ()),
    ("serve.py for the ops dashboard", ["src/serve.py"], "2026-03-17T21:45:00+05:30", ()),
    ("readme + handover", ["README.md", "HANDOVER.md"], "2026-03-27T17:55:00+05:30", ()),
]
for i, (msg, paths, when, rm) in enumerate(HIST):
    for rel, text in STAGES.get(i, {}).items():
        (REPO / rel).write_text(text, encoding="utf-8")
    commit(msg, paths, when, rm)
(REPO / "config/secrets.env").unlink()
(REPO / "config").rmdir()

# --------------------------------------------------------------------------- the sealed truth
DEFECTS = [
    dict(id="D01", kind="correctness", file="src/features.py", symbol="promised_window_hours",
         what="Uses timedelta.seconds instead of total_seconds(). Any promise of 24 hours "
              "or more wraps: a 72-hour promise becomes 0.0 and a 60-hour promise becomes "
              "12.0. Nothing crashes; the feature is silently wrong on most rows.",
         evidence="Take one row where promised_ts - pickup_ts is 72 hours and print the "
                  "feature. It is 0.0. Count rows where the value is smaller than the true gap.",
         decision="fix"),
    dict(id="D02", kind="leakage", file="src/prep.py", symbol="NUM_COLS",
         what="actual_transit_hours and delivery_attempts are outcomes, not inputs. Both are "
              "only known after the shipment finishes. is_late is transit > promised, so "
              "actual_transit_hours plus promised_window_hours IS the label.",
         evidence="Drop both columns and retrain. The reported score collapses.",
         decision="fix"),
    dict(id="D03", kind="leakage", file="src/features.py", symbol="courier_late_rate",
         what="Target encoding computed over the whole file, so every row's feature includes "
              "that row's own outcome and the outcomes of shipments that had not happened yet.",
         evidence="For a courier with few rows the feature moves when you flip one label. "
                  "Recompute it from past rows only and the score drops.",
         decision="fix"),
    dict(id="D04", kind="split", file="src/train.py", symbol="train_test_split",
         what="shuffle=True on a file sorted by pickup time. Test rows sit between training "
              "rows in time, so the score answers a question nobody asked.",
         evidence="Sort by pickup_ts, cut the last three months as the test set, retrain. "
                  "The score falls, and it falls most on GatiRoad.",
         decision="fix"),
    dict(id="D05", kind="evaluation", file="scripts/report.py", symbol="main",
         what="Scores the model on the full shipment file, which contains every training row. "
              "The weekly 'model health' number the ops team reads is a memory test.",
         evidence="Score only rows the model never saw and compare the two numbers.",
         decision="fix"),
    dict(id="D06", kind="train-serve-drift", file="src/prep.py", symbol="scale / encode",
         what="Scaling means and standard deviations, and category codes, are recomputed from "
              "whatever frame is passed. Training uses statistics of 12,000 rows; serving uses "
              "statistics of one row, where the standard deviation is 0 and the code is 0. The "
              "same shipment gets a different probability alone than it does in a batch.",
         evidence="Call load_and_predict on one shipment, then on the same shipment inside a "
                  "batch of 200. Compare the two probabilities.",
         decision="fix"),
    dict(id="D07", kind="train-serve-drift", file="src/features.py", symbol="courier_late_rate",
         what="At serve time there is no is_late column, so every shipment receives 0.5 for "
              "the feature the handover note calls the strongest one.",
         evidence="Print the feature frame inside serve for one request.",
         decision="fix"),
    dict(id="D08", kind="portability", file="config.py", symbol="DATA_PATH / MODEL_PATH",
         what="Absolute paths on the intern's laptop. The repo cannot run anywhere else.",
         evidence="Clone into a fresh folder and run train. It fails on the first read.",
         decision="fix"),
    dict(id="D09", kind="portability", file="requirements.txt", symbol="whole file",
         what="No versions pinned, and tabulate is missing although scripts/report.py calls "
              "to_markdown() which needs it.",
         evidence="Install from requirements.txt in a clean venv and run the report.",
         decision="fix"),
    dict(id="D10", kind="tests", file="(whole repo)", symbol="tests/",
         what="No tests exist. The README tells you to run pytest tests/.",
         evidence="ls tests/",
         decision="fix"),
    dict(id="D11", kind="documentation", file="README.md", symbol="whole file",
         what="Four claims the code does not support: accuracy 0.94 on held-out data (the "
              "split is not held out and the features leak); src/serve.py --port 8000 (serve.py "
              "has no CLI and no server); scripts/report.py --week last (no argument parsing); "
              "pytest tests/ (no tests). The feature list also omits the two leaked columns.",
         evidence="Run each command in the README exactly as written.",
         decision="fix"),
    dict(id="D12", kind="secret", file="config/secrets.env", symbol="git history",
         what="A database URL with a password, a maps API key and a Slack webhook were "
              "committed, then removed in a later commit. Deleting a file does not delete it "
              "from history; every clone still carries it.",
         evidence="git log --all -p -- config/secrets.env",
         decision="fix - and the fix starts with rotating the credentials, not with git"),
    dict(id="D13", kind="performance", file="src/features.py", symbol="courier_late_rate",
         what="A nested loop over all rows for every row. On 12,000 rows that is 144 million "
              "comparisons, and it runs on every training run and every request.",
         evidence="Time the build() call. Then time a version using one pass and a dictionary.",
         decision="fix"),
    dict(id="D14", kind="performance", file="src/serve.py", symbol="load_and_predict",
         what="joblib.load runs inside the request path, so the model is read from disk for "
              "every single shipment scored.",
         evidence="Time 50 calls. Then move the load to module import and time 50 again.",
         decision="fix"),
    dict(id="D15", kind="LEAVE IT", file="src/sla.py", symbol="calc",
         what="UGLY BUT CORRECT. Four-argument function with one-letter names, magic numbers "
              "and no comments. It is also exactly right, including the monsoon exception "
              "(tier 3 only, June to September, plus 12 hours), the festival exception "
              "(standard service only, October and November, plus 24 hours) and the "
              "long-haul rule above 1400 km. The handover note says the tier 3 logic is wrong. "
              "The handover note is wrong.",
         evidence="Run calc over all 12,000 rows and compare against promised_ts - pickup_ts. "
                  "It matches on every row, including the exceptions.",
         decision="LEAVE IT. Rename nothing, rewrite nothing. Wrap it in a characterisation "
                  "test and move on. A team that rewrites this loses the two exceptions and "
                  "nobody will notice until the next monsoon."),
]
SEALED.mkdir(exist_ok=True)
(SEALED / "DO_NOT_OPEN_UNTIL_STAGE_1_IS_SUBMITTED.json").write_text(
    json.dumps(dict(
        note="Opening this before your findings register is submitted is the one way to fail "
             "stage 1 outright. It is here so you can mark yourselves afterwards.",
        planted_defects=len([d for d in DEFECTS if d["kind"] != "LEAVE IT"]),
        leave_it_traps=len([d for d in DEFECTS if d["kind"] == "LEAVE IT"]),
        defects=DEFECTS), indent=2), encoding="utf-8")

# --------------------------------------------------------------------------- the receipt
def rate(sub):
    return f"{sum(r['is_late'] for r in sub) / max(1, len(sub)):.3f}"


late = sum(r["is_late"] for r in rows)
cut = rows[int(len(rows) * 0.8)]["pickup_ts"]
early = [r for r in rows if r["pickup_ts"] < cut]
recent = [r for r in rows if r["pickup_ts"] >= cut]
wrapped = sum(1 for r in rows
              if (datetime.fromisoformat(r["promised_ts"]) - datetime.fromisoformat(r["pickup_ts"])
                  ).total_seconds() / 3600.0 >= 24)
print("shipments              :", len(rows))
print("  date range           :", rows[0]["pickup_ts"][:10], "to", rows[-1]["pickup_ts"][:10])
print("  late                 :", late, f"(rate {late / len(rows):.3f})")
print("  ALWAYS-ON-TIME acc   :", round(1 - late / len(rows), 4), "<- beat this or you have nothing")
print("  first 80% by date    :", f"n={len(early)} late {rate(early)}")
print("  last  20% by date    :", f"n={len(recent)} late {rate(recent)}  <- the honest test set")
print("  late rate by courier, first 80% -> last 20%:")
for c in COURIERS:
    print(f"    {c:<17}", rate([r for r in early if r['courier'] == c]), "->",
          rate([r for r in recent if r['courier'] == c]))
print("  promise >= 24h       :", wrapped, f"({wrapped / len(rows):.3f}) <- rows D01 silently corrupts")
print("git commits            :", subprocess.run(["git", "rev-list", "--count", "HEAD"],
      cwd=REPO, capture_output=True, text=True).stdout.strip())
print("files in the repo      :", len(FILES) - 1, "(config/secrets.env is gone from disk, not from history)")
print("planted defects        :", len([d for d in DEFECTS if d["kind"] != "LEAVE IT"]),
      "| leave-it traps:", len([d for d in DEFECTS if d["kind"] == "LEAVE IT"]))
print("repo                   :", REPO.resolve())
print("sealed answers         :", (SEALED / "DO_NOT_OPEN_UNTIL_STAGE_1_IS_SUBMITTED.json").resolve())
print("DO NOT OPEN the sealed file until your stage 1 findings register is submitted.")

# P5 ACCEPTANCE CRITERIA. A stage is DONE when every row is true.

STAGE 1 - ARCHAEOLOGY. CHANGE NOTHING.
 1.1  make_inherited_repo.py run unedited; its receipt pasted into
      docs/inherited_receipt.md with your Python version.
 1.2  Not one line of delay-predictor/ source is edited in this stage.
      Prove it: git status is clean and git log shows no new commits
      on the inherited history.
 1.3  docs/code_map.md - every file, what it does, what calls it, and
      what it reads or writes. A stranger must navigate from this page.
 1.4  docs/history_notes.md - what the 13 commits tell you that the
      current code does not. Name the commit that created the fake
      score and the commit that proves credentials exist in history.
 1.5  docs/handover_audit.md - every claim in HANDOVER.md copied out
      and marked verified, refuted or unverified, with the evidence.
 1.6  docs/findings.md - the findings register, artefact 3's columns.
      Every row carries evidence a reviewer can reproduce alone.
 1.7  The ugly-but-correct file is in the register with the decision
      LEAVE IT, and the evidence that earns it.
 1.8  A per-person page: which files each member read, and one
      question each could not answer from reading alone.

STAGE 2 - THE SAFETY NET. STILL NO FIXES.
 2.1  tests/ exists with a pytest run that is green on the BROKEN code.
 2.2  A characterisation test per public function, pinning today's
      output including the wrong output.
 2.3  At least one test runs over the full 18,000 rows, not a sample.
 2.4  The ugly-but-correct function is characterised against the data
      it must agree with, and the match count is in the test name or
      its assertion message.
 2.5  A serving test that captures today's train-serve behaviour: the
      same shipment alone and inside a batch, both values recorded.
 2.6  Every test names WHICH defect it will catch, in a docstring.
 2.7  Proof the suite works: break one line on a scratch branch, paste
      the red output, discard the branch.
 2.8  A one-command entry point: make test, or a documented pytest line.

STAGE 3 - TRIAGE AND PLAN
 3.1  Every register row scored for risk (1-5) and effort (1-5), with
      one sentence of reasoning on each score.
 3.2  A ranked list, risk first and effort second, agreed by the team.
 3.3  An explicit OUT OF SCOPE list. At least two items, with reasons.
 3.4  One owner and one branch name per in-scope defect. Branch names
      carry the defect id.
 3.5  Split by FILE, not by preference. No two people own defects in
      the same file in the same round.
 3.6  docs/decisions.md open with 5+ dated entries, each naming the
      option rejected.
 3.7  A written role roster for all six stages: integrator, reviewer,
      scribe, rotating so each member does each role.
 3.8  A dated plan a lead could read in two minutes.

STAGE 4 - FIX IN SMALL SAFE STEPS
 4.1  One defect, one branch, one pull request. No exceptions.
 4.2  Every fix PR contains the fix AND the test that proves it, and
      the PR body names the characterisation test that changed.
 4.3  When a characterisation test goes red, the PR explains WHY the
      change is correct and updates the pinned value deliberately.
 4.4  The honest re-measurement table, one row per change: inherited,
      leaks removed, split by date, courier rate rebuilt from the past,
      plus the always-on-time baseline on the same rows.
 4.5  The honest score is reported with the number of test rows and
      the date cutoff beside it, in the README.
 4.6  Per-segment scores by courier, not only the average.
 4.7  The credential finding is handled in the right order: rotation
      first, history second, prevention third, all three written down.
 4.8  Every merged PR has at least one review comment that changed
      the code, from someone other than the author.

STAGE 5 - COLLABORATE UNDER LOAD
 5.1  No branch older than one working day at any point, shown by
      git log --graph in your report.
 5.2  A real merge conflict, resolved deliberately, with the
      resolution in its own commit naming what was kept and why.
 5.3  The suite is run after every conflict resolution, before commit.
 5.4  A review checklist used on every PR, pasted in the repo.
 5.5  One recorded disagreement, the experiment that settled it, and
      the result - including the case where the experiment lost.
 5.6  The role roster was actually followed, evidenced by who merged
      which PR.
 5.7  decisions.md reaches 12+ dated entries.
 5.8  Nobody merged their own pull request.

STAGE 6 - HAND OVER
 6.1  The clone test, run by somebody outside the team, on a machine
      that has never seen the project, timed, with the transcript.
 6.2  A README that is TRUE: every command in it was run, in order,
      on that clean machine.
 6.3  requirements.txt pinned with ==, and complete.
 6.4  docs/runbook.md - retrain, score, roll back, and who to call.
 6.5  HANDOVER_FROM_US.md - what we fixed, what we did not, what we
      are unsure about, and the three things we would do next.
 6.6  Every unfixed defect from the register appears in that note.
 6.7  The sealed file is opened at last, and docs/self_marking.md
      lists what you found, what you missed, and what you called
      wrongly - including anything you marked broken that was not.
 6.8  Per-person defence rehearsed against artefact 6.

# docs/findings.md    delay-predictor, inherited 2026-04-06
# One row per finding. Evidence must be reproducible by a reviewer alone.

| id  | defect (observable behaviour) | evidence (command + what you saw) | risk 1-5 | effort 1-5 | decision |

EXAMPLE OF A ROW THAT IS ACCEPTED
| F03 | promised_window_hours returns 0.0 for a 72-hour promise, so the
        feature is wrong on nearly every row and nothing raises an error
      | python -c "from src.features import *" over row 4117: CSV holds
        pickup 2025-06-14 09:00 and promised 2025-06-17 09:00, a 72-hour
        gap; the feature returns 0.0. 17,625 of 18,000 rows are affected.
      | 4 | 1 | FIX - own branch, own test |

EXAMPLE OF A ROW THAT IS REJECTED
| F09 | prep.py is badly written and probably causes problems
      | the code looks confusing
      | 5 | 3 | rewrite the whole file |
  Why rejected: "badly written" names no behaviour, "looks confusing" is
  not reproducible, and a risk of 5 cannot be defended when no
  consequence has been stated. Rewrite it as an observation plus a
  command, or delete the row.

EXAMPLE OF THE ROW EVERY TEAM GETS WRONG
| F11 | src/sla.py calc() is unreadable: four one-letter arguments,
        magic numbers, forty lines of nested branches, no comments
      | ran calc() over all 18,000 rows and compared with
        promised_ts - pickup_ts: 18,000 of 18,000 match, including
        the June-September tier-3 rows and the October-November
        standard rows
      | 1 | 4 | LEAVE IT - characterise, document the rules it
                encodes, do not rewrite |

THE FOUR RULES OF THIS FILE
  1. Evidence is a command and an observation, never an adjective.
  2. Risk is about consequence, not about how much the code annoys you.
  3. Effort is your estimate; write it before you know the answer and
     do not edit it afterwards. Compare at stage 6.
  4. A claim from HANDOVER.md enters as UNVERIFIED and leaves as
     VERIFIED or REFUTED. Never as a defect on the author's word.

# tests/test_characterise_sla.py
# WHAT THIS CATCHES: any change to src/sla.py that alters a promised
# window. It does NOT claim calc() is correct. It claims calc() agrees
# with the promised_ts already stored in the shipment file, on every row.
import pandas as pd
import pytest

from src.sla import calc

DATA = "data/shipments.csv"


@pytest.fixture(scope="module")
def rows():
    df = pd.read_csv(DATA, parse_dates=["pickup_ts", "promised_ts"])
    df["true_hours"] = (df.promised_ts - df.pickup_ts).dt.total_seconds() / 3600.0
    return df


def test_calc_matches_every_promised_window(rows):
    """Pins the SLA rule against 18,000 rows of real promises."""
    got = [calc(r.dest_tier, r.service_level, r.distance_km, r.pickup_ts.month)
           for r in rows.itertuples()]
    mismatches = rows[[g != t for g, t in zip(got, rows.true_hours)]]
    assert len(mismatches) == 0, (
        f"{len(mismatches)} of {len(rows)} rows disagree; first offenders:\n"
        f"{mismatches.head()[['shipment_id', 'dest_tier', 'service_level', 'distance_km', 'true_hours']]}")


@pytest.mark.parametrize("tier,service,km,month,hours,rule", [
    (3, "standard",  380,  7,  108, "monsoon: tier 3, Jun-Sep, +12"),
    (3, "standard",  380,  4,   96, "same lane outside the monsoon"),
    (2, "standard",  310, 10,  108, "festival: standard, Oct-Nov, +24"),
    (2, "express",   310, 10,   48, "festival rule does NOT apply to express"),
    (3, "standard", 1580,  2,  144, "long haul above 1400 km, +24"),
])
def test_the_three_exceptions_are_pinned(tier, service, km, month, hours, rule):
    """Each row is a business rule that exists nowhere else in writing."""
    assert calc(tier, service, km, month) == hours, rule

# TEAM CONTRACT - delay-predictor takeover

ROLES, ROTATING EACH STAGE (write the roster in decisions.md)
  INTEGRATOR  merges to main, one PR at a time, in order. Never merges
              their own PR. Announces every merge with the files it
              touched. Runs the suite on main after each merge.
  REVIEWER    reads every diff. May not approve without either running
              the branch or naming the test that convinced them.
  SCRIBE      owns decisions.md and findings.md. Writes entries the day
              the decision happens, never at the end of the week.
  Everyone codes. These three jobs sit on top of coding, and they move
  every stage so all four of you do each one at least once.

BRANCHES
  one defect -> one branch -> one PR.  fix/D02-drop-leaked-columns
  Open the PR the day you start, in draft if it is not ready.
  No branch lives longer than one working day. If it must, say so in
  standup and name the file it touches.
  git pull --rebase origin main every morning, before you touch code.

BEFORE YOU OPEN A SHARED FILE
  Say the file name out loud in the group. Thirty seconds here removes
  the merge that eats an afternoon. If it is already owned this round,
  queue behind that person or take a different defect.

THE PR RULES
  Title:  fix(D02): drop post-outcome columns from NUM_COLS
  Body:   what defect, the evidence line from findings.md, which
          characterisation tests changed and why that is correct, the
          before and after numbers with test-row counts.
  Size:   if the diff is over ~150 lines, it is two PRs.
  A PR with no test is a PR with no evidence.

REVIEW CHECKLIST - the reviewer answers all six, in writing
  1. Does this PR fix exactly one defect from the register?
  2. Is there a test that fails without the fix? Did you see it fail?
  3. Did any characterisation test change? Is the new value explained?
  4. Does it touch a file somebody else owns this round?
  5. Any number in the PR body reproducible by me from this branch?
  6. What is the blast radius if this is wrong in production?
  Comment style: name the line, state the risk as behaviour, say what
  evidence closes it. "Looks good" is not a review. Taste comments go
  in as suggestions and never block a merge.

CONFLICTS
  Resolve with the other author present. Read both sides aloud and
  decide which BEHAVIOUR is correct - not which side is yours.
  Run the suite BEFORE committing the resolution.
  The resolution is its own commit: "resolve: keep X over Y because Z".
  Never resolve a conflict two hours before a demo. Postpone the merge.

DISAGREEMENT
  1. State both positions in one sentence each, in decisions.md.
  2. Name the smallest experiment that settles it. Run it. Record it.
  3. If no experiment can settle it, the integrator decides for this
     stage and the log records who was overruled. Revisit at stage 6.
  Nobody re-argues a logged decision. That is what the log is for.

STANDUP, 10 MINUTES, SAME TIME DAILY
  What I merged. What I am in now, and which FILE. What is blocking me.
  Anyone who has not pushed in 24 hours says why, without blame.

WORKING SOLO
  You play all three roles, one at a time, in writing, and the
  artefacts are identical. Open a PR against your own repo. Leave the
  six review answers as comments on your own diff, then answer them in
  a second comment before you merge. Keep the same role roster and
  write which hat you are wearing in decisions.md. In stage 5,
  manufacture a conflict on purpose: branch twice from main, edit the
  same lines of src/features.py both times, and merge both.

# P5 GRADING. Total 100. TEAM 45, INDIVIDUAL 55.

TEAM MARKS - 45, from the acceptance criteria above
  Stage 1  archaeology, register, handover audit ......  10
  Stage 2  characterisation suite ....................    8
  Stage 3  triage, ranking, ownership plan ...........    5
  Stage 4  fixes, tests, honest re-measurement .......   12
  Stage 5  git workflow under load, decision log .....    5
  Stage 6  clone test, README, runbook, handover .....    5

INDIVIDUAL DEFENCE - 55, live, 15 minutes each, no notes on screen,
teammates OUT OF THE ROOM and forbidden to answer for anyone.

  I1  THE WHOLE SYSTEM (10)
      Full: 90 seconds - what you inherited, what was wrong with it,
      what you changed, what the honest number is, what is still
      broken. Ends with an offer to go deeper.
      Half: correct but over three minutes, or misses "still broken".
      Zero: describes only the part you personally wrote.
  I2  YOUR OWN COMMITS (12)
      Full: open your PRs by name, read your own diff aloud, name the
      test that proves each fix, and state what would break if your
      change were reverted.
      Half: finds the files, cannot explain the test.
      Zero: cannot locate your own commits, or another member has to
      find them for you.
  I3  SOMEBODY ELSE'S FIX (10)
      Full: explain a defect you did NOT fix - what it was, how it was
      proved, how it was fixed, and which number it moved.
      Zero: "that was their part". This is the most common failure in
      this rubric and it is the one that matters at work.
  I4  THE NUMBERS (10)
      Full: inside three seconds each - row count, base rate, the
      always-on-time baseline, the inherited score, the honest score,
      the honest ROC-AUC, recall, and the courier where it is worst.
      Half: two lookups needed.
      Zero: cannot state the honest score or the baseline.
  I5  THE TRAP (5)
      Full: name the ugly-but-correct file, state the evidence that
      earned LEAVE IT, and name the business rules a rewrite would
      have deleted.
      Zero: your team rewrote it, or cannot say why it was kept.
  I6  LIVE MODIFICATION (8)
      One change, in the team's code, while watched. Examples: put a
      leaked column back and predict the score before running it;
      delete the monsoon branch in sla.py and predict which test goes
      red; change the split cutoff by a month and predict the
      direction. Full: names the file, the function, the number that
      will move AND its direction, edits, runs, reads the result, and
      says whether the prediction held.
      Half: correct reasoning, cannot complete the edit.
      Zero: asks for time, or describes the change in general words.

THE OVERRIDE, and it is not negotiable:
  A member who cannot explain the system and cannot modify the code
  scores ZERO individually, whatever the repo looks like and however
  much they contributed on paper. Team marks are released only after
  every member has attempted I1 to I6. This is ruling 2 of the course:
  the defence IS the assessment, because generated code cannot be
  detected and an owner can always be questioned.

  A SECOND OVERRIDE, specific to this project:
  A team that reports a score produced with any post-outcome column,
  or that reports a number it cannot reproduce live from its own repo
  in one command, caps at 40 overall. The honest number is the
  deliverable. There is no partial credit for a comfortable one.

SOLO STUDENTS
  Same 100 marks, same rubric, same 15 minutes. I3 becomes "explain
  the defect you fixed FIRST, from memory, and what you would tell a
  new joiner about it". Expect harder probing on your self-review
  comments and on your manufactured merge conflict, because those are
  the two artefacts a solo route weakens.