Communicate bruh

PROJECT CONTEXT:
I'm building "Rail Samanvay" — an AI-powered block scheduling optimization 
system for Indian Railways (Smart India Hackathon project, PS 26027). The 
full system will eventually have a Python AI microservice (ML scoring + 
OR-Tools optimization), a Node.js/Express backend, and a React frontend.

RIGHT NOW: We are ONLY doing Phase 1 (Data Foundation). Do NOT build any 
ML model, optimizer, backend API, or frontend UI in this task. Phase 1 is 
purely about scaffolding the repo and producing clean, verified datasets.

=== TASK 1: Scaffold the monorepo ===
Create this folder structure at the project root:

rail-samanvay/
├── apps/
│   ├── frontend/        (empty for now, just a placeholder README)
│   └── backend/          (empty for now, just a placeholder README)
├── services/
│   └── ai-engine/
│       ├── data/
│       │   ├── raw/         <- I will manually place stations.json and 
│       │                       schedules.json here myself
│       │   └── processed/   <- your output goes here
│       ├── scripts/
│       └── venv setup
├── packages/             (empty for now, placeholder README)
├── turbo.json
├── package.json          (root, with npm workspaces: "apps/*", "packages/*")
└── README.md

Set up turbo.json and root package.json with npm workspaces pointing to 
apps/* and packages/* only (the Python service is NOT part of the 
Turborepo pipeline — it's managed independently). Confirm this works by 
running `npx turbo run build` and showing me it doesn't error, even with 
empty apps.

=== TASK 2: Set up the Python environment ===
Inside services/ai-engine, create a Python virtual environment. Install 
pandas and numpy only (nothing else yet — no FastAPI, no XGBoost, no 
OR-Tools, those come in a later phase). Create a requirements.txt with 
just these two.

=== TASK 3: Filter the real dataset for our corridor ===
I will place stations.json and schedules.json in 
services/ai-engine/data/raw/. Write a Python script 
(scripts/01_filter_corridor.py) that:

1. Loads both JSON files with pandas.
2. Filters stations.json to only stations matching our corridor (match by 
   station NAME first, normalized to uppercase with whitespace stripped, 
   since station CODES vary between informal indicator letters and 
   official IR codes across different data sources — name matching is 
   more reliable here). Use this exact station list, in order:

   SHARED TRUNK (CSMT to Kalyan):
   Chhatrapati Shivaji Maharaj Terminus (CSMT/CST/CSTM), Masjid, 
   Sandhurst Road, Byculla, Chinchpokli, Currey Road, Parel, Dadar, 
   Matunga, Sion, Kurla, Vidyavihar, Ghatkopar, Vikhroli, Kanjurmarg, 
   Bhandup, Nahur, Mulund, Thane, Kalwa, Mumbra, Diva, Dombivli, 
   Thakurli, Kalyan Junction (KYN)

   BRANCH 1 (Kalyan to Igatpuri, via Thal Ghat):
   Kalyan Junction, Shahad, Ambivli, Titwala, Khadavli, Vasind, Asangaon, 
   Atgaon, Thansit, Khardi, Umbermali, Kasara (KSRA), Igatpuri (IGP)

   BRANCH 2 (Kalyan to Karjat, via Bhor Ghat direction):
   Kalyan Junction, Thansit, Vithalwadi, Ulhasnagar, Ambarnath, Badlapur, 
   Vangani, Shelu, Neral, Bhivpuri Road, Karjat (KJT)

   Note: Kalyan Junction appears in all three lists deliberately — it's 
   the shared fork point. Don't deduplicate it away; we need it 
   represented once in the master station list but referenced by both 
   branches downstream.

3. Filters schedules.json to only rows whose station_code or 
   station_name matches the filtered station list from step 2 (try 
   matching on both fields since real data can be inconsistent — flag 
   any station from my list above that gets ZERO matches in the 
   schedules data, so I know if a name/code mismatch needs fixing).
4. Saves the filtered stations to 
   data/processed/corridor_stations.csv
5. Saves the filtered schedules to 
   data/processed/corridor_schedules_real.csv
6. Prints a summary: total stations matched (out of the ~48 listed 
   above), total schedule rows matched, and a list of any stations from 
   my list that had zero schedule matches.

=== TASK 4: Build the block sections table ===
Write scripts/02_build_block_sections.py that:

1. Loads corridor_stations.csv
2. Generates consecutive station pairs as "block sections" — each row is 
   one section between two adjacent stations, following the branching 
   structure above (shared trunk CSMT→Kalyan, then two separate branches 
   from Kalyan). 
3. For each block section, add columns: section_id (auto-generated), 
   from_station, to_station, branch ("trunk" / "igatpuri_branch" / 
   "karjat_branch"), is_ghat_section (True only for sections physically 
   within the Kasara-Igatpuri climb or the Karjat-side ghat climb — mark 
   your best guess based on station order, I'll manually verify this 
   after), electrified (True for all, this corridor is fully 
   electrified), line_category (mark "fast+slow" for the trunk since it 
   has multiple lines, "single/double" for the branches — best guess is 
   fine, I'll refine).
4. Save as data/processed/block_sections.csv
5. Print the full table so I can visually confirm the Kalyan fork looks 
   correct (Kalyan should appear as the end of the trunk AND the start 
   of both branches).

=== TASK 5: Generate the synthetic suburban local layer ===
Write scripts/03_generate_synthetic_locals.py that:

1. Loads block_sections.csv and corridor_schedules_real.csv
2. Generates synthetic EMU local train schedule rows, matching the SAME 
   column structure as corridor_schedules_real.csv (so they can be 
   merged), following this realistic hourly frequency pattern for each 
   block section on the trunk (CSMT-Kalyan, since that's where real 
   suburban density matters most):
   - 05:00-06:00: moderate (~8 trains/hour)
   - 06:00-11:00: peak (~15-18 trains/hour)
   - 11:00-17:00: moderate (~10 trains/hour)
   - 17:00-21:00: peak (~15-18 trains/hour)
   - 21:00-00:00: moderate (~6 trains/hour)
   - 00:00-05:00: sparse (~1-2 trains/hour, mainly 00:00-01:00, then 
     near-zero 01:00-04:00)
   For the ghat branches (Kasara-Igatpuri, Karjat side), use a much 
   lower frequency overall (~3-5 trains/hour at peak, ~1/hour off-peak) 
   since these aren't dense suburban sections.
   Generate this for every day for one representative week.
   Tag every synthetic row with a column is_synthetic = True (real rows 
   from Task 3 should be tagged is_synthetic = False when you merge them 
   later).
3. Save as data/processed/synthetic_locals.csv

=== TASK 6: Merge and verify ===
Write scripts/04_merge_and_verify.py that:

1. Merges corridor_schedules_real.csv and synthetic_locals.csv into one 
   file: data/processed/train_movements_final.csv
2. Produces a simple verification chart (matplotlib is fine, add it to 
   requirements.txt) showing: hourly train count for the CSMT-Kalyan 
   trunk, across one full day. Save as data/processed/verification_chart.png
3. Print whether the chart shows a visible rush-hour pattern (two peaks, 
   roughly 6-11am and 5-9pm, with a clear late-night trough 1-4am) — this 
   is the pass/fail check for this whole phase. If it doesn't show this 
   pattern clearly, flag it and explain what looks wrong.

=== DELIVERABLE ===
After all 6 tasks, give me a summary: what was built, where each output 
file lives, the verification chart, and explicitly confirm or deny that 
the pass/fail check in Task 6 passed. Do not proceed to any ML, backend, 
or frontend work beyond this — stop here and wait for my review.

PROJECT CONTEXT:
Continuing "Rail Samanvay" — Phase 1 is complete and verified: 
services/ai-engine/data/processed/ contains block_sections.csv and 
train_movements_final.csv. Repo structure (apps/, services/ai-engine/, 
packages/, turbo.json) is already scaffolded.

RIGHT NOW: Phase 2 only — generate the synthetic defects dataset, then 
build and train the AI priority scoring model. Do NOT build the 
optimizer, FastAPI wrapper, backend, or frontend in this task. Stop 
after the model is trained, evaluated, and exported.

=== TASK 1: Set up ML dependencies via uv ===
In services/ai-engine, ensure a pyproject.toml exists (create one if it 
doesn't, using the existing venv/dependencies from Phase 1 as the base 
dependency list: pandas, numpy, matplotlib). Add an optional dependency 
group named "ml" containing: scikit-learn, xgboost, joblib. Run 
`uv sync --extra ml` and confirm all packages import successfully with a 
quick `python -c "import xgboost, sklearn, joblib"` check.

=== TASK 2: Generate the synthetic defects dataset ===
Write scripts/05_generate_defects.py that creates realistic maintenance 
defect records across our three departments, linked to block sections 
from block_sections.csv. Generate roughly 800-1200 defect records total, 
spread across a simulated 12-month period, with these columns:

- defect_id (unique)
- department: "Engineering" / "S&T" / "TRD" (roughly balanced across all 
  three, since real Railways coordination involves all of them)
- block_section_id (foreign key into block_sections.csv — sample 
  realistically, weight slightly more defects toward ghat sections and 
  high-traffic trunk sections, since those see more wear)
- defect_type: 
  - For Engineering: one of IMR, OBS, IMRW, OBSW, DFWO, DFWR (per the 
    real RDSO USFD Manual classification we researched)
  - For S&T: one of "maintainer_fixable" or "escalated_beyond_competence" 
    (per Signal Engineering Manual II — S&T genuinely has no severity 
    scale, only this binary, so don't force a fake severity label here)
  - For TRD: one of "major_defect" or "minor_defect" (per ACTM 20322-5/6 
    — major gets reported immediately to TPC, minor goes into the depot 
    register)
- date_reported (random date across the simulated year)
- days_overdue (numeric, realistic distribution — most defects resolved 
  within their statutory window, a smaller tail overdue significantly)
- location_criticality: "normal" / "tunnel" / "bridge_or_approach" / 
  "near_weld_hole" — sample so most are "normal", a meaningful minority 
  fall in the elevated-risk categories (this maps to USFD Annexure IIA's 
  location-weighted severity rule — a defect in a tunnel or near a bridge 
  gets escalated severity even if it would otherwise be lower-priority)
- section_traffic_density: pull the average hourly train count for that 
  block_section_id from train_movements_final.csv (join on 
  block_section_id)
- is_ghat_section: pull directly from block_sections.csv for that section
- season_restriction_flag: True if date_reported falls in a monsoon 
  month (June-September) AND the defect is on a ghat section (per our 
  seasonal research — heavy machine work is restricted in monsoon, 
  especially on ghat sections)

Save as data/processed/defects.csv. Print value counts for department 
and defect_type to confirm realistic distribution (not badly skewed to 
one department or type).

=== TASK 3: Build the rule-based training label ===
Write scripts/06_build_training_labels.py that computes a "true_priority_score" 
(0-100 scale) for every defect in defects.csv, using this weighted logic 
as the BASE formula:

- Base severity weight: IMR/IMRW = 85, DFWR = 80, OBS/OBSW = 45, 
  DFWO = 40, escalated_beyond_competence = 70, maintainer_fixable = 30, 
  major_defect (TRD) = 75, minor_defect (TRD) = 35
- Location multiplier: normal = 1.0x, tunnel = 1.4x, bridge_or_approach = 
  1.3x, near_weld_hole = 1.25x (reflecting USFD's real location-weighted 
  severity escalation rule — cap the final score at 100 after applying)
- Add +0.5 points per day_overdue, capped at +25 total contribution
- Add a traffic density contribution: +0.1 points per average train/hour 
  on that section, capped at +10
- Add +8 points if season_restriction_flag is True (delay risk is 
  compounded when the work is also time-restricted)

THEN, critically, inject controlled randomness and one deliberate 
non-linear interaction so the ML model has something genuine to learn 
beyond the linear formula:
- Add Gaussian noise (mean 0, std ~5) to every score
- Deliberate interaction: if is_ghat_section is True AND 
  section_traffic_density is in the top 25% of values AND department is 
  "S&T", add an EXTRA +15 points on top of the base formula (this 
  simulates a real-world pattern where signal defects on busy ghat 
  sections are disproportionately riskier than the linear formula alone 
  would suggest — we're testing whether the trained model can pick up on 
  this interaction that a simple weighted-sum formula misses)

Clip final scores to the 0-100 range. Save the labeled dataset as 
data/processed/defects_labeled.csv. Print the score distribution 
(histogram description: min, max, mean, std) and specifically print the 
average score for the injected-interaction subgroup vs. everyone else, 
so I can see the gap exists before we even train anything.

=== TASK 4: Feature engineering and train/test split ===
Write scripts/07_train_priority_model.py that:

1. Loads defects_labeled.csv
2. Encodes categorical columns (department, defect_type, 
   location_criticality) — use one-hot encoding via 
   sklearn.preprocessing or pandas get_dummies, save the encoder/column 
   structure so it can be reused later for scoring new single records
3. Splits into train (70%), validation (15%), test (15%) — random split 
   is fine, use a fixed random_state for reproducibility
4. Trains an XGBoost regressor (xgboost.XGBRegressor) predicting 
   true_priority_score from all engineered features EXCEPT the raw 
   defect_id, date_reported, and block_section_id (those are identifiers, 
   not predictive features)
5. Use reasonable default hyperparameters to start (n_estimators=200, 
   max_depth=5, learning_rate=0.1) — don't over-engineer hyperparameter 
   tuning in this pass, that's a later refinement

=== TASK 5: Evaluate the model ===
Write scripts/08_evaluate_and_export.py that:

1. Computes RMSE and R² on the held-out test set, prints both
2. Extracts and prints XGBoost feature importance (gain-based), sorted 
   descending — I want to see the top 5 features by name
3. Specifically checks: does the model, when predicting on the 
   ghat+high-traffic+S&T subgroup from Task 3, show elevated average 
   predictions compared to the rest of the test set (similar to the gap 
   we injected)? Print both averages side by side so I can visually 
   confirm the model learned the interaction, not just the linear terms
4. Saves a feature importance bar chart as 
   data/processed/feature_importance.png
5. Exports the trained model using joblib to 
   services/ai-engine/models/priority_scorer.pkl, and separately exports 
   the encoder/column structure from Task 4 to 
   services/ai-engine/models/feature_encoder.pkl

=== TASK 6: Build a standalone scoring test script ===
Write scripts/score_defect_cli.py — a small, simple script (NOT a FastAPI 
endpoint, just a runnable script) that:
1. Loads priority_scorer.pkl and feature_encoder.pkl
2. Takes one hardcoded example defect (you choose realistic values) as 
   input
3. Prints the predicted priority score AND the top 3 features that 
   contributed most to that specific prediction (use 
   model.feature_importances_ combined with the actual feature values 
   for this record — a simple explanation is fine, doesn't need to be 
   full SHAP-level rigor at this stage)

This is a rough proof-of-concept for what will later become the 
/score-defects API endpoint in Phase 4 — but for now it's just a script 
I can run manually to sanity-check the model works end to end.

=== DELIVERABLE ===
After all 6 tasks, give me a summary: dataset size and distribution, 
RMSE/R² on test set, top 5 feature importances, whether the injected 
interaction was successfully learned (with the two averages you 
computed), and the output of running score_defect_cli.py once. 
Explicitly state pass/fail: PASS if R² is reasonably high (>0.80) AND 
the interaction-subgroup gap is visible in the model's predictions 
(even if smaller than the injected +15, it should clearly be higher than 
the rest, not flat/random). Do not proceed to the optimizer, backend, or 
FastAPI work — stop here and wait for my review.

PROJECT CONTEXT:
Continuing "Rail Samanvay" — an AI-powered block scheduling optimization
system for Indian Railways (Smart India Hackathon project, PS 26027).

Phase 1 (Data Foundation) is complete and verified:
services/ai-engine/data/processed/ contains block_sections.csv and
train_movements_final.csv (real + synthetic suburban local layer, merged,
rush-hour pattern verified).

Phase 2 (ML Priority Scoring) is complete and verified:
services/ai-engine/data/processed/ additionally contains defects.csv and
defects_labeled.csv. services/ai-engine/models/ contains priority_scorer.pkl
(trained XGBoost regressor) and feature_encoder.pkl (matching column
structure). R² and the injected ghat+traffic+S&T interaction gap were both
confirmed on the held-out test set.

Repo structure (apps/, services/ai-engine/, packages/, turbo.json) is
already scaffolded and untouched by this phase.

RIGHT NOW: Phase 3 only — the Optimization Engine. This phase turns
"we can score how urgent a defect is" into "we can actually build a
conflict-free, resource-respecting weekly/monthly block schedule" using
Google OR-Tools CP-SAT, per Section 3.2 of TECHNICAL_PLAN.md. Do NOT build
the FastAPI wrapper, the Node/Express backend, or any React frontend in
this task — those are Phase 4 and Phase 5. This phase produces standalone,
runnable Python scripts only, tested from the command line. Stop after the
solver runs successfully on the full defect set and the output schedule is
verified — wait for review before touching FastAPI/backend/frontend.

=== TASK 1: Add the optimization dependency group ===
In services/ai-engine, extend the existing pyproject.toml (built in Phase
2) with a new optional dependency group named "opt" containing: ortools.
Run `uv sync --extra opt` and confirm it imports successfully with
`python -c "from ortools.sat.python import cp_model"`. Do not touch the
existing "ml" group or its packages.

=== TASK 2: Generate the remaining synthetic resource/constraint datasets ===
Three datasets from our original 9-dataset plan (TASK.md items #7, #8, #9)
were deferred until now because the optimizer is the first thing that
actually consumes them. Write scripts/09_generate_resource_data.py that
produces all three in one script:

1. **Machine/crew resource pool** → data/processed/machines.csv
   Columns: machine_id, machine_type (BCM / tamper / PQRS / OHE-maintenance-
   van / signal-testing-van — map realistically to which department each
   machine type serves), home_depot (pick 2-3 depots along our corridor,
   e.g., Kalyan, Kasara, Karjat), min_block_duration_minutes (per the real
   rule we researched: track machines need one block of at least 4 hours,
   OR two blocks of 2.5 hours each — encode this as a duration requirement
   per machine_type, don't just invent numbers). Generate a realistic small
   fleet (not one machine per defect — the whole point is scarcity creates
   contention for the solver to resolve). Roughly 8-15 machines total across
   all types is enough to create real contention without being unsolvable.

2. **Pre-committed corridor block calendar (standing corridors)** →
   data/processed/standing_corridors.csv
   Columns: corridor_id, block_section_id, day_of_week, from_time, to_time,
   department. These are recurring windows already reserved in the annual
   working timetable — BEFORE the optimizer ever runs, these times are
   already unavailable on their block_section_id, regardless of what the
   solver wants to schedule. Generate a modest number of these (a handful
   per week, weighted toward ghat sections where standing maintenance
   corridors are more common in real practice) so the "available windows"
   calculation in Task 3 has something real to subtract.

3. **Seasonal/working-season restrictions** →
   data/processed/seasonal_restrictions.csv
   Columns: restriction_id, month, work_type_restricted, reason. Encode the
   real rule we already used in Phase 2's season_restriction_flag logic:
   heavy machine work (BCM/tamper-class) is restricted on ghat sections
   during monsoon months (June-September). Keep this consistent with how
   defects.csv's season_restriction_flag was computed — the optimizer's
   constraint must actually block scheduling heavy-machine work on ghat
   sections in those months, not just carry the flag as metadata.

Print row counts and a short description of each table so I can sanity
check them before they feed the solver.

=== TASK 3: Define block-section conflict/adjacency logic in code ===
This is dataset #2b from TASK.md — deliberately code, not a table. Write
scripts/10_conflict_rules.py as an importable module (not just a script)
containing a function `sections_conflict(section_id_a, section_id_b,
block_sections_df) -> bool` that returns True if blocking both sections
at the same time is unsafe/not permitted. At minimum, implement:
- Identical section → always conflicts with itself.
- Adjacent sections sharing a station (e.g., two consecutive block
  sections meeting at the same station) → conflict, since work at the
  shared station affects both.
- Any section conflicts with itself across the Kalyan fork logic — i.e.
  a section ending at Kalyan Junction on the trunk conflicts with a
  section starting at Kalyan Junction on either branch, since Kalyan
  Junction is the shared physical point.
Include a small inline test at the bottom of the file (run as
`python scripts/10_conflict_rules.py`) that prints conflict/no-conflict
for a handful of hand-picked section pairs so I can visually confirm the
logic is sane before the solver depends on it.

=== TASK 4: Compute available scheduling windows ===
Write scripts/11_compute_available_windows.py that, for our planning
horizon (use the same representative week generated in Phase 1's
synthetic locals, extended conceptually to a 4-week "month" by repeating
the weekly pattern — note this simplification explicitly in the script's
docstring), does the following per block_section_id per day:

1. Starts from train_movements_final.csv and computes hourly traffic
   density (trains/hour) per section per day — reuse the same aggregation
   logic Phase 2 used for section_traffic_density.
2. Identifies candidate low-traffic windows: contiguous time ranges where
   traffic density is below a threshold you choose and justify (e.g.,
   below the 25th percentile for that section), long enough to fit at
   least the shortest real block duration we have (2.5 hours per the
   machine rule from Task 2).
3. Subtracts any time already claimed by standing_corridors.csv for that
   section/day (already reserved, not available to compete for).
4. Subtracts time blocked by seasonal_restrictions.csv where applicable
   (work-type-specific, so this becomes a per-work-type filter downstream
   rather than a blanket subtraction — pass this through as a flag per
   window rather than removing the window entirely, since a window might
   be fine for non-restricted work).
5. Saves the result as data/processed/available_windows.csv with columns:
   window_id, block_section_id, day, start_time, end_time,
   duration_minutes, avg_traffic_density, season_restricted_for
   (nullable — which work types can't use this window, if any).

Print total candidate windows generated, and a spot-check: total windows
on the CSMT-Kalyan trunk vs. the ghat branches (trunk should have fewer,
shorter windows given higher traffic; ghat branches should have more/
longer ones — flag it if this isn't the case, since it would mean the
threshold logic is wrong).

=== TASK 5: Score pending defects and prepare optimizer input ===
Write scripts/12_prepare_optimizer_input.py that:

1. Loads defects.csv (NOT defects_labeled.csv — in the live system we
   only have the model's predicted score, not the ground-truth formula
   score; using true_priority_score here would be cheating the demo).
2. Loads priority_scorer.pkl and feature_encoder.pkl from Phase 2, applies
   the same encoding pipeline, and generates a predicted_priority_score
   for every defect.
3. Maps each defect to a required block duration based on department/
   defect_type (Engineering IMR/IMRW-class → BCM-length work → 4hr or
   2×2.5hr per Task 2's machine rules; lighter defect types → shorter
   durations — use your judgment grounded in what we researched, and
   state your assumptions in a comment block at the top of the script).
4. Maps each defect to a required machine_type (e.g., Engineering defects
   need BCM/tamper, S&T needs signal-testing-van, TRD needs OHE-
   maintenance-van) so the solver knows which machines from machines.csv
   are eligible for which defect.
5. For this phase, take the top ~150-250 highest-scored pending defects
   as our active planning pool (state and justify the exact number you
   pick) — this keeps the first full solver run tractable while still
   being a real, non-trivial optimization problem. Save this as
   data/processed/optimizer_input_defects.csv.

Print the size of the active pool, its score distribution, and department
breakdown.

=== TASK 6: Build the CP-SAT model and test on a small scenario FIRST ===
Write scripts/13_build_solver_small_test.py that builds the actual OR-Tools
CP-SAT model, but runs it ONLY on a hand-picked or randomly sampled 15-20
defects from optimizer_input_defects.csv before we trust it on the full
set — per the Phase 3 roadmap in TECHNICAL_PLAN.md Section 7 ("test with a
small synthetic scenario (10-20 requests) before scaling up"). Implement:

**Variables:** For each pending defect, a decision of which available
window (from available_windows.csv) it is assigned to, plus which eligible
machine (from machines.csv) it uses. Use OR-Tools interval variables or
boolean assignment variables — whichever pattern is cleaner for this
model; explain your choice briefly in a code comment.

**Constraints (all must be hard constraints the solver cannot violate):**
- A defect can only be assigned to a window whose duration meets its
  required block duration.
- A defect can only be assigned a machine of its required machine_type.
- No single machine can be assigned to two overlapping windows (use
  Task 3's conflict logic — resolve section-level scheduling conflicts,
  not just literal time overlap, since two different sections can still
  conflict per sections_conflict()).
- No two defects assigned to conflicting block sections (per Task 3's
  sections_conflict()) can occupy overlapping time windows.
- A defect whose required work type is season_restricted_for a given
  window cannot be assigned to that window.
- Not every defect must be scheduled in this pass (that's realistic —
  there's genuinely more work than capacity) — but track which ones go
  unscheduled.

**Objective:** Maximize total priority-score-weighted defects scheduled,
i.e. maximize sum of predicted_priority_score over all successfully
scheduled defects. (State in a comment that later phases could add a
secondary objective term to prefer scheduling similar-priority items
sooner rather than later — but keep it single-objective for this pass.)

Run the solver on the small test set, print: solver status (OPTIMAL /
FEASIBLE / INFEASIBLE), solve time, how many of the 15-20 test defects got
scheduled vs. left pending, and a readable printout of the resulting
mini-schedule (defect_id → section → day/time → machine).

If it comes back INFEASIBLE, do not silently loosen constraints — report
exactly which constraint is unsatisfiable given the test inputs and
suggest the fix, so I can decide how to adjust rather than have the
model quietly change the rules.

=== TASK 7: Scale to the full active pool ===
Once Task 6 produces a sane, correct small-scale schedule, write
scripts/14_run_full_optimization.py that runs the same CP-SAT model
(import the model-building logic from Task 6 rather than duplicating it —
refactor Task 6's model construction into a reusable function first if
needed) against the full ~150-250 defect optimizer_input_defects.csv pool.

1. Set a solver time limit (start with 60 seconds; CP-SAT doesn't need to
   find the mathematically perfect optimum for a hackathon demo — note in
   a comment that "OPTIMAL" vs "FEASIBLE within time limit" is a real,
   honest distinction worth keeping visible in the output, not hiding).
2. Save the resulting schedule as
   data/processed/schedule_assignments.csv with columns: defect_id,
   block_section_id, day, start_time, end_time, machine_id,
   predicted_priority_score, department.
3. Save the list of defects that could NOT be scheduled this cycle as
   data/processed/unscheduled_defects.csv (this is a real, useful output —
   it's exactly what a "spilled over" report would show in BDMS terms).
4. Print: solver status, solve time, total defects scheduled vs.
   unscheduled, and average predicted_priority_score of scheduled vs.
   unscheduled groups (scheduled should skew meaningfully higher — that's
   the whole point of the objective function; flag it if it doesn't).

=== TASK 8: Verify the schedule is actually valid ===
Write scripts/15_verify_schedule.py as an independent check — it should
NOT reuse the solver's internal state, it should re-derive validity from
schedule_assignments.csv alone, as if auditing someone else's output.
Check and report pass/fail on each of the following:
1. No machine appears in two overlapping time windows anywhere in the
   output.
2. No two scheduled defects occupy overlapping windows on conflicting
   block sections (recheck against sections_conflict() from Task 3).
3. Every scheduled defect's window duration meets its required minimum.
4. No scheduled defect violates a season restriction for its work type.
5. No scheduled window overlaps a standing_corridors.csv entry.

Then compute a small before/after impact summary for the pitch deck
later: % of top-quartile-priority defects (by predicted_priority_score)
that got scheduled vs. left pending, and total scheduled work hours by
department. Save this summary as
data/processed/optimization_impact_summary.csv (a small, human-readable
table, not a raw dump).

=== DELIVERABLE ===
After all 8 tasks, give me a summary covering:
- What resource/constraint datasets were generated (Task 2) and their
  sizes.
- Confirmation the conflict/adjacency logic (Task 3) passed its inline
  sanity checks.
- Available windows generated (Task 4) and the trunk-vs-ghat spot check
  result.
- Size and composition of the active defect pool sent to the optimizer
  (Task 5).
- Small-scenario solver result (Task 6): status, solve time, schedule
  correctness.
- Full-scale solver result (Task 7): status, solve time, scheduled vs.
  unscheduled counts, priority-skew check.
- Verification results (Task 8): pass/fail on all five checks, plus the
  impact summary numbers.
- Explicitly state overall PASS/FAIL for this phase: PASS requires the
  small-scenario solve to be OPTIMAL or FEASIBLE with a correct schedule,
  the full-scale solve to complete within the time limit with a non-empty
  valid schedule, and all five Task 8 checks passing.

Do not proceed to the FastAPI wrapper, Node backend, or React frontend —
stop here and wait for my review.

PROJECT CONTEXT:
Continuing "Rail Samanvay" — an AI-powered block scheduling optimization
system for Indian Railways (Smart India Hackathon project, PS 26027).

Phase 1 (Data Foundation) is complete: services/ai-engine/data/processed/
contains block_sections.csv and train_movements_final.csv.

Phase 2 (ML Priority Scoring) is complete: defects.csv, defects_labeled.csv,
and services/ai-engine/models/priority_scorer.pkl +
feature_encoder.pkl (trained XGBoost regressor + its encoder).

Phase 3 (Optimization Engine) is complete and verified: machines.csv,
standing_corridors.csv, seasonal_restrictions.csv, available_windows.csv,
optimizer_input_defects.csv, schedule_assignments.csv,
unscheduled_defects.csv, and optimization_impact_summary.csv all exist in
data/processed/. scripts/10_conflict_rules.py (importable conflict-check
module) and the CP-SAT model-building logic from
scripts/13_build_solver_small_test.py / 14_run_full_optimization.py all
work correctly, verified independently by scripts/15_verify_schedule.py.

IMPORTANT STACK CORRECTION going into this phase: TECHNICAL_PLAN.md
originally proposed a Node.js/Express main backend calling a separate
Python FastAPI microservice. That is NOT what we're building. Our locked
stack is React + Vite + Tailwind (frontend, not yet started) + FastAPI
(the ONE and ONLY backend) + OR-Tools CP-SAT (already built, Phase 3) +
PostgreSQL (database) + Docker Compose (orchestration). There is no
Node.js anywhere in this project. The empty apps/backend/ folder created
as a placeholder in Phase 1's scaffold was reserved for a Node service
that we are no longer building — retire it in Task 1 below rather than
building anything inside it.

RIGHT NOW: Phase 4 only — the Backend Layer. This phase takes everything
Phases 1-3 built as standalone scripts operating on CSV files, and turns
it into a real, running FastAPI application backed by PostgreSQL: proper
tables, auth, CRUD endpoints, and the AI/optimization logic exposed as
REST endpoints instead of command-line scripts. Do NOT build any React
frontend in this task — that's Phase 5. Do NOT redesign the ML model or
the CP-SAT constraints — reuse Phase 2/3 logic as-is, just refactored to
read from the database instead of CSVs. Stop after the smoke test in
Task 8 passes — wait for review before starting frontend work.

=== TASK 0: Retire the unused Node placeholder ===
Replace the contents of apps/backend/README.md with a short note: this
project uses a single FastAPI backend (services/ai-engine), this folder
is intentionally unused, kept only so the original monorepo layout stays
intact. Do not create any package.json, server file, or dependency inside
apps/backend/ — it should remain an empty placeholder with just that
README.

=== TASK 1: Stand up PostgreSQL via Docker Compose ===
At the project root, create/extend docker-compose.yml with a `postgres`
service:
- Use the official postgres:16 (or latest stable 16.x) image.
- Database name: rail_samanvay, with a dedicated user/password read from
  a .env file (create .env.example with placeholder values, and a real
  .env — add .env to .gitignore if it isn't already).
- Mount a named volume so data persists across restarts.
- Expose the standard port (5432) to the host for local development.
- Add a healthcheck (pg_isready) so dependent services can wait for it.
Confirm it works: `docker compose up -d postgres` then connect with
`psql` (or a quick Python script using psycopg2/asyncpg) and confirm the
empty database is reachable.

=== TASK 2: Define the database schema ===
In services/ai-engine, add SQLAlchemy (add to pyproject.toml's base
dependencies, not a new optional group — this is core, not optional) and
create services/ai-engine/db/models.py defining ORM models for every
table, matching the CSV structures already produced by Phases 1-3 as
closely as possible so migration is a straightforward column mapping,
not a redesign:

- block_sections (from block_sections.csv)
- train_movements (from train_movements_final.csv)
- defects (from defects.csv — keep true_priority_score OUT of this table;
  that lived only in defects_labeled.csv for training and should not leak
  into the live system's data model)
- machines (from machines.csv)
- standing_corridors (from standing_corridors.csv)
- seasonal_restrictions (from seasonal_restrictions.csv)
- schedule_assignments (from schedule_assignments.csv, PLUS an
  approval_status column: enum "pending_review" / "approved" / "rejected"
  / "overridden", defaulting to "pending_review" — this is new, it didn't
  exist in the Phase 3 CSV output because there was no human-in-the-loop
  concept yet; add it now since Section 4.1/5 of TECHNICAL_PLAN.md
  requires officials to approve/override AI suggestions)
- users (id, name, role — one of "depot_incharge" / "tpc" / "coa_official"
  / "divisional_controller", mirroring the real BDMS roles we researched;
  department, hashed_password)

Set up Alembic (or a simple create_all() bootstrap script if you judge
Alembic to be overkill for our timeline — state which you chose and why)
so the schema can be created from nothing with one command. Run it against
the Task 1 database and confirm all tables exist with correct columns
(print the table list from Postgres to verify).

=== TASK 3: Load Phase 1-3 CSV outputs into the database ===
Write services/ai-engine/scripts/16_load_csvs_to_db.py that reads every
processed CSV from Phases 1-3 (block_sections, train_movements_final,
defects, machines, standing_corridors, seasonal_restrictions,
schedule_assignments — NOT defects_labeled.csv, NOT
optimizer_input_defects.csv, NOT unscheduled_defects.csv, NOT
optimization_impact_summary.csv, since those are intermediate/training
artifacts, not live system state) and inserts them into the matching
Postgres tables via the SQLAlchemy models from Task 2. Use bulk insert,
not row-by-row, for the train_movements table given its size. Handle the
schedule_assignments load specially: every row gets
approval_status="pending_review" on initial load, since these were AI-
generated in Phase 3 and haven't been reviewed by a human yet.
Print row counts inserted per table, and reconcile them against the
source CSV row counts to confirm nothing was silently dropped.

=== TASK 4: Refactor Phase 2 & Phase 3 logic into reusable service
functions (not endpoints yet) ===
Before writing any FastAPI route, extract the actual logic so routes stay
thin. Create:
- services/ai-engine/core/scoring_service.py — a function
  `score_defects(defect_records: list[dict]) -> list[dict]` that loads
  priority_scorer.pkl + feature_encoder.pkl once (cache at module load,
  don't reload the model on every call) and returns predicted priority
  scores + the top-3-feature explanation per record, reusing the logic
  from Phase 2's score_defect_cli.py.
- services/ai-engine/core/optimization_service.py — a function
  `generate_schedule(defect_records: list[dict], available_windows: ...,
  machines: ..., existing_assignments: ... = None) -> dict` that wraps
  the CP-SAT model-building logic from Phase 3's
  13_build_solver_small_test.py / 14_run_full_optimization.py, returns
  the schedule assignments + unscheduled list + solver status/solve time.
  Accept an optional `existing_assignments` parameter specifically to
  support Task 6's /reoptimize endpoint — when provided, previously
  approved assignments (approval_status="approved") should be treated as
  fixed/locked in the solver, not re-shuffled, while pending ones are
  free to move.
Write a quick standalone test (a small script or pytest test, your
choice) confirming both functions still produce results consistent with
what Phases 2 and 3 already validated, now running from these importable
functions instead of the original scripts.

=== TASK 5: Build the FastAPI application skeleton ===
Create services/ai-engine/main.py (or app/main.py if you prefer a
package layout — pick one and be consistent) wiring up:
- Database session dependency (SQLAlchemy session per request, proper
  connect/disconnect lifecycle).
- JWT-based auth: POST /api/auth/login (username/password against the
  users table, returns a JWT), and a dependency that protects the routes
  below by requiring a valid token. Keep this simple — no need for
  refresh tokens or password reset flows in a hackathon build, just
  working login + protected routes.
- CORS middleware configured to allow the future frontend's origin
  (localhost:5173 for Vite dev, plus a placeholder for the deployed URL).

=== TASK 6: CRUD + AI endpoints ===
Implement these routes (organize into routers by resource, e.g.
routers/defects.py, routers/schedule.py, routers/auth.py):

- `GET /api/defects` — list defects, with query-param filters for
  department, block_section_id, and a min-days-overdue threshold.
- `POST /api/defects` — add a new defect (this is what powers the "inject
  an urgent defect live" demo moment later). On creation, automatically
  call scoring_service.score_defects() for just this one record and store
  its predicted score back on the row.
- `GET /api/schedule` — return current schedule_assignments, joined with
  defect and block_section info so the frontend doesn't need N+1 calls.
- `POST /api/schedule/generate` — pulls all currently unscheduled/pending
  defects + available_windows + machines from the DB, calls
  optimization_service.generate_schedule(), writes the results into
  schedule_assignments (approval_status="pending_review"), returns the
  new schedule + solver stats (status, solve time, scheduled/unscheduled
  counts).
- `POST /api/schedule/{assignment_id}/approve` — sets approval_status to
  "approved" (official reviewing the AI's suggestion).
- `POST /api/schedule/{assignment_id}/reject` — sets approval_status to
  "rejected".
- `POST /api/schedule/reoptimize` — accepts a new defect (or a defect_id
  already in the DB) representing an urgent mid-cycle addition, re-runs
  optimization_service.generate_schedule() with existing approved
  assignments locked (per Task 4), returns the updated schedule — this is
  the literal implementation of the "live demo" moment described in
  TECHNICAL_PLAN.md Section 5, item 6.
- `GET /api/analytics` — summary stats: total defects by department,
  % scheduled vs. pending, average predicted_priority_score of scheduled
  vs. unscheduled (mirrors the impact numbers from Phase 3's
  optimization_impact_summary.csv, but computed live from current DB
  state instead of a static file).

All endpoints except /api/auth/login require a valid JWT.

=== TASK 7: Wire FastAPI into Docker Compose ===
Add a second service to docker-compose.yml: `ai-engine` (the FastAPI app),
built from a Dockerfile in services/ai-engine/ (write this Dockerfile —
base on a slim Python image, install via uv or pip, copy code, run
uvicorn). Configure it to depend_on postgres with the healthcheck
condition, and read DB connection details from the same .env used in
Task 1. Confirm `docker compose up` brings up both postgres and ai-engine
cleanly, and the FastAPI app is reachable (e.g., GET /docs shows the
Swagger UI) without needing anything running on the host manually.

=== TASK 8: End-to-end smoke test ===
Write services/ai-engine/scripts/17_smoke_test.py — a script using
httpx or requests (NOT pytest, this should be runnable standalone and
print a readable pass/fail trace) that, against the running
docker-compose stack, does the full realistic flow in order:
1. Logs in, gets a JWT.
2. Fetches current /api/defects, confirms non-empty (data from Task 3's
   load).
3. Fetches current /api/schedule, confirms non-empty (Phase 3's
   schedule_assignments, loaded in Task 3).
4. Approves a handful of pending schedule assignments via
   /api/schedule/{id}/approve.
5. Posts a new high-urgency defect via POST /api/defects, confirms it
   comes back with a predicted priority score attached.
6. Calls /api/schedule/reoptimize with that new defect, confirms the
   response includes it in either the scheduled or unscheduled list, and
   confirms the previously-approved assignments from step 4 were NOT
   moved (this is the "locked assignments" behavior from Task 4/6 — check
   it explicitly, don't just assume it worked).
7. Fetches /api/analytics, confirms the numbers make sense (non-zero,
   percentages between 0-100).
Print a clear PASS/FAIL per step, and an overall pass/fail for the whole
flow.

=== DELIVERABLE ===
After all 8 tasks, give me a summary covering:
- Confirmation apps/backend/ was retired cleanly (Task 0).
- Database schema created (Task 2) — list of tables and a one-line note
  per table on what changed vs. the Phase 1-3 CSV structure (especially
  the new approval_status column and the true_priority_score exclusion).
- Row counts loaded per table (Task 3), reconciled against source CSVs.
- Confirmation the refactored scoring/optimization service functions
  (Task 4) still validate against Phase 2/3's known-good results.
- Full endpoint list actually implemented (Task 6), with method + path
  for each.
- Docker Compose status (Task 7): both services healthy, /docs reachable.
- Full smoke test output (Task 8), step by step.
- Explicit overall PASS/FAIL: PASS requires Docker Compose bringing up
  both services cleanly AND every step of the Task 8 smoke test passing,
  including the "approved assignments stay locked during reoptimize"
  check specifically.

Do not proceed to the React frontend — stop here and wait for my review.

=== PHASE 1 ===
...
=== PHASE 2 ===
======================================================================
TASK 2 — Generating synthetic defects…
======================================================================
Generated 1000 defects.
...
======================================================================
TASK 5 — Evaluating Model…
======================================================================
Test RMSE : 5.7301
Test R²   : 0.9379

Top 5 Features by Importance:
                       Feature  Importance (Gain)
      defect_type_minor_defect           0.302202
defect_type_maintainer_fixable           0.271350
              defect_type_DFWO           0.123741
               defect_type_OBS           0.093102
              defect_type_OBSW           0.087427
...
=== PHASE 3 ===
...
======================================================================
TASK 4 — Computing available scheduling windows…
======================================================================
Total candidate windows generated: 1,324
...
======================================================================
TASK 7 — Full-Scale CP-SAT Optimization
======================================================================
Pool size : 200 defects
Windows   : 1,324
Machines  : 13
Time limit: 60 seconds

Solving…

  Solver Status : OPTIMAL
  Solve Time    : 2.37s
  Scheduled     : 136 / 200
  Unscheduled   : 64
...
======================================================================
TASK 8 — Independent Schedule Verification
======================================================================
[Check 1] No machine double-booked: ✅ PASS
[Check 2] No conflicting sections overlap: ✅ PASS
[Check 3] Duration meets minimum: ✅ PASS
[Check 4] No seasonal restriction violated: ✅ PASS
[Check 5] No standing corridor overlap: ✅ PASS

✅ ALL CHECKS PASS
...
=== PHASE 4 ===
Dropping and recreating all tables...
Loading Users...
  Inserted 4 users.
...
Loading ScheduleAssignments...
  Inserted 136 schedule assignments.

✅ Database loaded successfully.

--- Step 1: Login ---
✅ PASS: Login successful, got JWT.

--- Step 2: Fetch current defects ---
✅ PASS: Fetched 1000 defects.

--- Step 3: Fetch current schedule ---
✅ PASS: Fetched schedule with 136 assignments.

--- Step 4: Approve first 3 pending assignments ---
✅ PASS: Approved assignments for defects: ['DEF-20260232', 'DEF-20260322', 'DEF-20260833']

--- Step 5: Post new high-urgency defect ---
✅ PASS: Defect created and auto-scored: 92.36

--- Step 6: Reoptimize schedule with locked assignments ---
✅ PASS: Approved assignments remained locked and untouched.
✅ PASS: New urgent defect was analyzed (added to unscheduled pool due to constraints).

--- Step 7: Analytics API ---
✅ PASS: Analytics retrieved. Scheduled: 13.6%

✅✅ OVERALL PASS: End-to-End Smoke Test Completed Successfully! ✅✅

PROJECT CONTEXT:
Continuing "Rail Samanvay" — an AI-powered block scheduling optimization
system for Indian Railways (Smart India Hackathon project, PS 26027).

Phase 1 (Data Foundation): block_sections.csv, train_movements_final.csv —
done.
Phase 2 (ML Priority Scoring): trained XGBoost model, R² 0.94 on held-out
test set — done.
Phase 3 (Optimization Engine): CP-SAT solver, verified schedule with all 5
independent validity checks passing (no machine double-booking, no
conflicting-section overlap, duration minimums respected, seasonal
restrictions respected, no standing-corridor overlap) — done.
Phase 4 (Backend Layer): single FastAPI backend (services/ai-engine),
PostgreSQL via Docker Compose, JWT auth, full CRUD + AI endpoints
(/api/defects, /api/schedule, /api/schedule/generate,
/api/schedule/{id}/approve, /api/schedule/{id}/reject,
/api/schedule/reoptimize, /api/analytics), end-to-end smoke test passing
including the "approved assignments stay locked during reoptimize" check
— done. apps/backend/ (the old Node placeholder) is retired and unused.

RIGHT NOW: Phase 5 only — the React Dashboard frontend, in apps/frontend/
(currently just a placeholder README from Phase 1's scaffold). Stack is
locked: React + Vite + Tailwind, talking to the Phase 4 FastAPI backend
over REST + JWT. Do NOT add a component library beyond Tailwind unless a
specific task below calls for a charting/calendar dependency — keep the
dependency footprint small, this is a hackathon build, not a production
app. Do NOT touch the backend, database, or ML/optimization logic in this
task — if the frontend needs something the API doesn't currently return,
flag it in your summary rather than silently modifying a Phase 4 file.
Do NOT do pitch-deck polish, animations-for-their-own-sake, or the
architecture diagram — that's Phase 6. Build in the exact order below;
each numbered task is a working, demoable increment, not just a
component — stop after Task 8 and wait for review.

=== TASK 1: Scaffold the app and wire up auth ===
Replace apps/frontend/'s placeholder with a real Vite + React (TypeScript)
+ Tailwind app.
1. `npm create vite@latest` (react-ts template) inside apps/frontend/,
   install Tailwind per their current official setup instructions.
2. Create a `.env.example` and `.env` with `VITE_API_URL` pointing at the
   Phase 4 FastAPI backend (default http://localhost:8000 for local dev
   against Docker Compose).
3. Build a small typed API client (services/api.ts or similar) wrapping
   fetch, that: attaches the JWT from storage to every request, redirects
   to /login on a 401, and exposes typed functions for every Phase 4
   endpoint (getDefects, createDefect, getSchedule, generateSchedule,
   approveAssignment, rejectAssignment, reoptimize, getAnalytics, login).
   Use React state (not localStorage-dependent logic beyond storing the
   raw token string, which is fine) — keep this simple.
4. Build a Login page: username/password form, calls POST /api/auth/login,
   stores the JWT, redirects to the main dashboard on success, shows a
   clear error on failure (wrong credentials, backend unreachable —
   distinguish these two cases in the message).
5. Set up React Router with a protected-route wrapper that redirects to
   /login if no valid token is present, wrapping every other route built
   in the tasks below.
6. Build a persistent app shell: a left sidebar or top nav with links to
   the views built in Tasks 2-6, showing the logged-in user's name/role
   and a logout button.

Confirm this works end-to-end against the real running Phase 4 backend
(via `docker compose up`) — log in with a real seeded user from the
Phase 4 users table, land on an empty/placeholder dashboard shell, and
confirm logout + redirect-when-unauthenticated both work.

=== TASK 2: Pending Requests view ===
Build the defects list view (this is TECHNICAL_PLAN.md Section 5, item 1
— build it first, it's simplest and shows the AI working immediately):
1. Table of defects from GET /api/defects: defect_id, department,
   defect_type, block_section (resolve to a readable name, not just the
   ID), days_overdue, predicted_priority_score, and a one-line
   auto-generated explanation string built from the score + top
   contributing factors already returned by the scoring endpoint (e.g.
   "High priority: IMR-class, 12 days overdue, ghat section" — construct
   this client-side from the fields you have, don't invent an endpoint
   for it).
2. Sort by predicted_priority_score descending by default, with column
   sort toggles.
3. Filter controls matching the API's existing query params: department,
   block_section, min-days-overdue.
4. Color-code or badge the priority score (e.g., a visual band for
   high/medium/low) so it's scannable at a glance, not just a number in a
   column.
5. An "Add Defect" button/form (feeds Task 7's live demo) that calls
   POST /api/defects and shows the newly created row with its auto-scored
   priority appearing in the table without a full page reload.

=== TASK 3: Schedule view (Gantt/calendar) ===
This is your single most visually important screen (TECHNICAL_PLAN.md
Section 5, item 2 — flagged there as "your single most visually
impressive demo piece"). Build it against GET /api/schedule:
1. Pick and justify a charting/calendar approach appropriate for a
   day-by-section timeline — a lightweight library is fine here (e.g. a
   Gantt-style library, or a hand-built CSS-grid timeline if you judge
   that faster and more controllable) — state which you chose and why in
   your summary, since this is the one place a new dependency is
   justified.
2. Rows = block sections (grouped by branch: trunk / igatpuri_branch /
   karjat_branch, matching Phase 1's structure), columns/x-axis = time
   across the planning horizon, blocks placed as colored bars showing
   defect_id, department (color-coded), and time range on hover/click.
3. Clicking a scheduled block opens a detail panel: full defect info,
   assigned machine, current approval_status.
4. Visually distinguish approval_status states (pending_review vs.
   approved vs. rejected vs. overridden) — color or icon, not just text
   buried in the detail panel.
5. A toggle or filter for week view vs. the full planning horizon, since
   TECHNICAL_PLAN.md explicitly calls for weekly AND monthly horizons.

=== TASK 4: Conflict alerts ===
(TECHNICAL_PLAN.md Section 5, item 3.) Since the CP-SAT solver already
guarantees the stored schedule has zero conflicts by construction (Phase
3's verification proved this), this view's job is different: surface
information that helps an official understand WHY the AI made its calls,
not hunt for bugs. Build a panel/tab showing:
1. The list of unscheduled/pending-generation defects (currently no
   assignment) ranked by predicted_priority_score, so it's visible which
   high-priority work is NOT yet covered — this is your "spilled over"
   equivalent from the real BDMS reports we researched.
2. For any two defects that request overlapping or adjacent block
   sections in the same rough time window but ended up scheduled at
   different times, a short "why these were kept apart" note — this can
   be computed client-side from data already in /api/schedule (same
   section family + close-in-time), it doesn't need a new backend field.
3. If GET /api/schedule doesn't return enough information to build #2
   cleanly, don't invent data — note exactly what additional field would
   be needed from the backend and skip to a simpler version of this view
   for now, flagged clearly in your summary.

=== TASK 5: Manual override controls ===
(TECHNICAL_PLAN.md Section 5, item 4 — explicitly flagged as important
for judge trust: this proves you're not removing human oversight from a
safety-critical system.) On the Schedule view's detail panel from Task 3:
1. Approve button → calls POST /api/schedule/{id}/approve, updates the UI
   state immediately (optimistic update is fine, but reconcile with the
   server response).
2. Reject button → calls POST /api/schedule/{id}/reject, same pattern.
3. A confirmation step before either action (a simple modal, not a full
   dialog library) — these are meant to feel like real operational
   decisions, not accidental clicks.
4. Reflect the updated approval_status immediately in both the detail
   panel and the Gantt view's color-coding from Task 3.

=== TASK 6: Analytics panel ===
(TECHNICAL_PLAN.md Section 5, item 5.) Build a dashboard summary view
against GET /api/analytics:
1. Headline numbers as cards: % of defects scheduled vs. pending, total
   scheduled work hours by department, average priority score of
   scheduled vs. unscheduled groups (this is literally the number that
   proves the AI is prioritizing correctly — make it prominent).
2. A simple chart (bar or pie, whichever is clearer) breaking down
   defects/schedule by department.
3. If time allows, a small "before/after" framing: e.g. "X high-priority
   defects would have waited under manual, ad-hoc scheduling — this run
   scheduled Y% of the top-quartile-priority pool" (compute top-quartile
   client-side from the defects already fetched in Task 2, no new
   backend work needed).

=== TASK 7: Live "what-if" demo mode ===
(TECHNICAL_PLAN.md Section 5, item 6 — explicitly your strongest live-
demo moment, practice-worthy for the finale.) Build a dedicated,
clearly-labeled "Demo Mode" screen or panel, separate from the normal
workflow so it doesn't get confused with real data entry during judging:
1. A form to inject a new high-urgency defect (pre-filled with a
   realistic, dramatic example — e.g. a tunnel-location IMR defect on a
   busy ghat section — so the presenter doesn't have to type during the
   pitch).
2. A big, obvious "Reoptimize Now" button that calls
   POST /api/schedule/reoptimize with that defect.
3. A clear before/after visual: show the schedule state right before the
   call, then animate/highlight what changed after — at minimum,
   highlight the newly added defect's outcome (scheduled where, or added
   to unscheduled pool) and confirm on-screen that previously approved
   assignments were NOT disturbed (this is the exact guarantee Phase 4's
   backend already provides — the UI's job is to make that guarantee
   visible to a judge watching, not just to trust it silently).
4. Solver stats (status, solve time) shown directly on this screen —
   "solved in 2.3 seconds" is a genuinely impressive thing to show live,
   don't bury it in a console log.

=== TASK 8: Docker integration and end-to-end verification ===
1. Add a `frontend` service to docker-compose.yml: build the Vite app
   (or run its dev server, your call — state which and why given our
   demo-vs-production tradeoff) and expose it on a fixed port, wired to
   reach the `ai-engine` service's URL correctly from inside Docker's
   network (note: this may differ from the browser's own VITE_API_URL,
   since the browser talks to the backend via the host's exposed port,
   not the internal Docker network — get this distinction right, it's a
   common source of "works in dev, breaks in Docker" bugs).
2. Run `docker compose up` from a clean state (postgres + ai-engine +
   frontend, all three) and manually walk through: login → Pending
   Requests → add a defect → Schedule view → approve one assignment →
   Analytics → Demo Mode → reoptimize. Confirm every step works against
   the fully containerized stack, not just against a locally-run `npm run
   dev` hitting a locally-run backend.
3. Note any environment-specific bugs you hit and fixed (these are
   exactly the kind of thing worth mentioning in your summary — Docker
   networking issues are common and worth flagging even after you fix
   them, so I know what to watch for later).

=== DELIVERABLE ===
After all 8 tasks, give me a summary covering:
- Confirmation the app scaffold + auth flow (Task 1) works against the
  real Phase 4 backend.
- Screens built (Tasks 2-7) and which TECHNICAL_PLAN.md Section 5 item
  each maps to.
- Which charting/calendar library you chose for the Gantt view (Task 3)
  and why.
- Any place the frontend needed data the backend doesn't currently
  provide (flagged per Task 4, if applicable) — list these explicitly so
  I can decide whether to patch Phase 4 before Phase 6.
- Full Docker Compose walkthrough result (Task 8), including any
  networking issues hit and how they were resolved.
- Explicit overall PASS/FAIL: PASS requires all three Docker Compose
  services running together cleanly AND the full manual walkthrough in
  Task 8, step 2, completing without errors.

Do not start Phase 6 (polish, architecture diagram, pitch deck prep) —
stop here and wait for my review.