Continuous Hierarchical Analysis — Phased Implementation Plan

Status: Implementation plan, v1.0 (2026-07-06). Companion to the design doc Continuous Hierarchical Video Analysis & the Live Bar Raiser. This doc owns the build order, phase gates, and per-phase scope; the design doc owns the full rationale.

How to use: each phase section below is written to seed a spec-kit specify → plan → tasks cycle. Cadence is build → deploy → soak one week → observe → continue. The recruiter report is never bet on unproven code, so scoring graduates through shadow → primary.

Live interactive version: https://www.html-docs.com/d/91377aac-6226-4b4e-9fec-bdf752ca235a?token=d2bb115b

Purpose and how to use this document

This is the phased implementation plan for continuous hierarchical video analysis — the how, in what order, behind which gates. The design doc (Utkrushta/docs/continuous-hierarchical-analysis.md) owns the why (architecture, window math, Bar Raiser, cost model, decisions D1-D14). On sequencing or scope this plan wins; for mechanism detail, defer to the design doc.

Its real job is to feed spec-kit: each phase section is a pre-spec seed — scope as user stories (P1/P2/P3), build list, seams touched, data-model delta, exit gate, out-of-scope — enough to run speckit specify → plan → tasks.

The cadence

Every phase moves on one rhythm: build → deploy → soak a week → observe → continue. Ship the code, put it in front of real or replayed traffic, watch the soak dashboards for a week, then start the next phase. These mechanisms are new to the team, so people operate them before more weight stacks on top.

Decision. The recruiter report (task_sessions.result_analysis) is the crown jewel — never bet on unproven code. Scoring moves to the new service through shadow → primary over two phases, not a deploy-day flip. The service writes only to a shadow table until a soak week proves byte-shape parity against the batch pipeline; only then does it earn the real column, with Fargate demoted to a still-trusted fallback.

The Phase 0-2 win is latency, not accuracy: the same v2 pipeline runs live, so scores match by construction — the report lands at T+4-9 min, not T+30-45. Accuracy and candidate-facing features arrive only in Phase 3.

How to read this document

Read in order; each section assumes the ones before.

1. Phasing overview

TL;DR. We move scoring off the batch Fargate container into a live Coolify service, so the recruiter report (task_sessions.result_analysis) lands at T+4-9 min instead of T+30-45. Ship in four phases, each on a build → deploy → soak-a-week → observe cadence:

• Phase 0 — build the service + scoring plane, prove it offline against recorded prod sessions.
• Phase 1 — run it live in prod, write to a shadow store only; Fargate still owns the report.
• Phase 2 — flip the report to the service — the latency win; Fargate demoted to standby.
• Phase 3 — add the candidate-facing awareness plane (nudges + chat), per-position opt-in.

The win is latency, not accuracy. The fallback: Fargate is never deleted — it stays on standby, and a Gemini sentinel makes each batch run a no-op when the live path already finalized, or a full rerun when it didn't.

Two planes drive the split. The scoring plane (Phases 0-2) is today's v2 pipeline run live, reusing airflow/dags/video_analysis verbatim (one pipeline, two runners). The awareness plane (Phase 3) is all new, fail-soft, and additive — it never enters the report (R-SHAPE). They share no runtime state, so scoring can go fully primary before a single nudge exists.

The four phases

Two decided framings

Decision. The Phase 1/2 win is latency, not accuracy. Phases 0-2 run the same v2 MAP + REDUCE over the same activity timeline as batch, so scores match by construction; only when the report lands changes (T+4-9 min vs T+30-45). Any accuracy change (finer L1 timeline, digest carry-chain) arrives only in Phase 3, and never enters scoring prompts (R-AWARE-SCORING). Sell "same report, sooner," not a quality upgrade.

Decision. Shadow exists because of the Gemini-sentinel hazard. The batch container treats any non-placeholder result_analysis as "already done" and no-ops, skipping chunk download, ffmpeg, and Gemini (core.py:1626-1641). That is what makes Fargate a free fallback — but it cuts both ways: a wrong or partial live write would silently promote broken code to primary. So in Phase 1 the service never writes result_analysis; shadow output goes to continuous_shadow_runs + S3 only (R-IDLE). Phase 2 lets it write the real column only after shadow proves parity.

Fargate stays registered on standby via FF_FARGATE_TASK_ANALYSIS (shared/feature_flags.py:24-33); Phase 2 re-triggers the same DAG (dag_run_id = client_submission_id) so post-steps (cert, notification, recommended) run once, and a failed live write falls through to a full batch run. The demotion is operational, not a code deletion.

Spec-kit slicing. Four features: scoring service — shadow (Phase 0+1, one codebase), scoring — primary + finalize seam (Phase 2), bar-raiser nudge engine and candidate chat (Phase 3). Prereqs P1-P5 land in parallel and gate phases (P4→0, P2/P3→1, P5→2 playback, P1→3). Near-serial spine — each exit gate is the next entry gate — realistic for a team of 1-2.

2. Shared mechanisms primer

Six mechanisms carry every phase. Defined once here; phase sections use them by name. Full rationale is in the design doc.

2.1 CAS and the lease

CAS is a conditional UPDATE guarded by an expected version — 0 rows updated means someone else moved first, so re-read and retry. Its canonical use is the running-digest fold (never let two folds win, never apply the same L2 twice):

UPDATE session_digests
   SET version = version + 1, digest = :folded, applied_l2 = applied_l2 || :l2_id
 WHERE tasksession_id = :ts AND task_id = :tid
   AND version = :expected        -- guard: nobody folded since we read
   AND NOT applied_l2 @> :l2_id;   -- never apply the same L2 twice
-- 0 rows ⇒ re-read, re-fold, retry

The lease gives one owner per session. Claim/steal and heartbeat are both CAS; every downstream write carries the lease_epoch it claimed under, so a stalled worker's late write lands 0 rows. On restart the lease expires within its 30 s TTL and any instance re-claims — deploys are drain-less.

UPDATE analyzer_sessions
   SET claimed_by = :me,
       lease_epoch = lease_epoch + 1,               -- new epoch fences the old owner
       lease_expires_at = now() + interval '30 seconds'
 WHERE tasksession_id = :ts
   AND (claimed_by IS NULL OR lease_expires_at < now())
 RETURNING lease_epoch;                             -- 0 rows ⇒ a live owner holds it

Decision. Ownership is a fenced lease row, not a Postgres advisory lock — Supabase's pooled access has no stable session to hold a lock on, and a lease row is inspectable and hands us an explicit fencing token (failure-modes §6).

2.2 One pipeline, two runners

Scoring logic lives in one import-clean directory, airflow/dags/video_analysis/. The Fargate image and the new session-analyzer image both COPY it at build — zero forks, only the runner differs. Phases 0-2 make the live path primary; the finalize seam still triggers Fargate on every submit, where its Gemini sentinel no-ops if result_analysis already exists (core.py:1626-1641) or runs the full batch fallback if it didn't.

Decision. Both CI path filters (.github/workflows/task-analysis-image.yaml and its new session-analyzer twin) must include airflow/dags/video_analysis/**. If they drift, one runner ships a stale pipeline — the most dangerous maintainability failure in this plan.

2.3 Stamps, digest, identity

The three stamps, digest-vs-L2, and per-task identity are captured in the table above. One frozen-config hazard is worth stating outright:

Warning. Window sizes freeze into analyzer_sessions.config at session start. Retuning l1_window_s/l2_window_s mid-session re-shards existing windows and breaks window_index idempotency (invariant I1); new sizes apply to new sessions only (failure-modes §4.7).

3. Prerequisite PRs (P1-P5)

Five small, independent fixes (the D14 prereqs). They land in parallel with — mostly before — Phase 0. None needs the session-analyzer service to exist, so all five can start now. P3 is the one hard blocker.

Warning. P3 is the only load-bearing blocker. Phase 1 shadow roughly doubles Gemini load on an unmeasured quota, using a key shared with the proctor pipeline — a shadow 429-storm could starve the real report and proctoring at once (I-8; followup-6.md §1-2). No shadow session runs until the separate GCP project, GEMINI_API_KEY_CONTINUOUS, and a recorded quota table all exist.

3.1 The five workstreams

• P1 — Resolver + context-payload field + tests; scopes feed nudge/chat judgment only.
• P2 — GEMINI_FLASH_PRICING (config.py:16-42) holds 2.5-flash rates and generate_tags is priced on the Pro table (core.py:2584), so every cost figure (incl. the $1.10 avg) under-reports ~40% input / ~17% output.
• P3 — Two deliverables: the recorded quota (first input to the 350-concurrent targets — Flash ≥1,000 RPM / ≥12M TPM, Pro ≥150 RPM / ≥3M TPM) and the isolated project/key; _DEV unblocks Phase 0 replay, prod key + quota is the Phase 1 blocker.
• P4 — Tiny PR: ACL param on the continuous S3 writer + a test asserting no public-read; replay is the first writer of these candidate-reasoning artifacts.
• P5 — ~30-min spike then PR; the single-session path already has a copy2 variant (core.py:1956-1961); no report flip until the MP4 exists on 100% of shadow sessions.

Decision. P1 injects skill scopes into awareness-plane prompts only (nudge + chat), never a scoring MAP/REDUCE prompt — the scoring plane stays byte-identical to batch so the score-parity claim holds (R-AWARE-SCORING).

Spec-kit: P1 and P5 are small standalone features; P2/P4 are plain PRs; P3 is an ops + env PR. Sequencing: land all five in parallel, close before Phase 0 sign-off.

4. Phase 0 — Build & Replay (offline)

At a glance

Decision. Phase 0 runs the scoring plane only — 20-min segment MAP + REDUCE + finalize-as-library over the existing CV activity-timeline pre-pass, exactly as batch runs it. L1/L2/digest, nudges, chat, and the EQ-4 timeline-recall gate are validated separately in Phase 3. Nothing algorithmic changes, so continuous-vs-batch deltas should collapse to the temperature-0.3 replicate floor.

Out of scope (→ owner)

In-scope = the build list. Deliberately left out:

Build list (→ FRs)

All new unless marked Reuse.

Seams touched (import-only, not edits — the two-runners rule)

Data-model delta (→ Key Entities)

• analyzer_sessions — one row per (tasksession_id, task_id): state machine (IDLE|LIVE|DRAINING|FINALIZING|DONE|FAILED_FALLBACK), lease (claimed_by, lease_expires_at, heartbeat, lease_epoch fencing), frozen config, task context. UNIQUE(tasksession_id, task_id).
• analysis_segments — scoring-plane 20-min MAP units: map_result, token_usage, latency_ms, chunk_range, status; PK (tasksession_id, task_id, segment_index).
• L1/L2 rows + session_digests → Phase 3; continuous_shadow_runs → Phase 1. In P0 the comparator writes only harness artifacts, never a report column.

Shared mechanisms in play

• Lease + fencing on analyzer_sessions; the restart fault proves reclaim-and-resume.
• CAS on segment claim (WHERE status='PENDING' AND lease_epoch=…); the digest CAS fold is Phase 3.
• Two runners — the Dockerfile COPYs video_analysis; CI path filter watches airflow/dags/video_analysis/** for both images. It is import-clean (Fargate proves it).
• Identity per (tasksession_id, task_id) — segments close on 1200s of per-task footage, not wall-clock or global chunk-count; a task switch closes the open segment early.

Exit gate — Measurable Success Criteria

Noise floor measured first (20 sessions × 2 batch runs at temperature 0.3) governs the relative thresholds. All must hold on the ≥50-session corpus before Phase 1.

Failure modes & kill switches

No kill switch is live in prod in P0; the circuit breaker (K-7), coverage-fallback (K-5), and lease-fencing are fire-drilled offline so they enter Phase 1 as tested code.

Observability, dependencies & assumptions

Watch (no prod soak; repeated replay passes accumulate the corpus + fault matrix):

• Better Stack continuous_* ops (_segment_map_done, _tail_map, _reduce, _finalize, _sweep, _lease_claim, _lease_lost, _coverage_gap, _circuit_open), each with latency_ms + token_usage + task_session_id — the source for retuning segment/grace knobs.
• Comparator report (md + JSON at s3://…/dag_reports/continuous_replay/{run}.md): EQ aggregates, EQ-3 flip list, EQ-5 citation sample, per-session drill-down.
• Dev cost/latency vs the batch $1.10 average (needs the P2 Flash-pricing fix, else ~40% under-report).
• One fault-run report per scenario: coverage accurate to ±1 window, no full-confidence output on a degraded run.

Dependencies:

Assumptions:

• Historical prod chunks still exist at deterministic S3 keys; the corpus builder verifies inventory and re-runs batch v2 for any missing baseline (26 sessions have full pipeline_metadata; the rest re-derived to reach ≥50).
• Corpus stratified by length (<20-min single-pass vs >40-min segmented; median footage ≈ 22 min), mechanism (GITHUB vs ZIP), ≥8 positions.
• Prompt 2.6.0 + calculator_v2 pinned identical across both pipelines for the whole window; any bump resets the comparison clock.
• Accelerated replay is valid because boundaries derive from (session_ts, chunk_num), not wall-clock; at temperature 0.3 the noise floor is measured before any delta is judged.

Spec-kit slicing

One spec-kit feature — "continuous scoring service — offline build & replay" — since the replay harness is the acceptance vehicle and belongs in the same spec.md. FRs cleave near-serially: (1) skeleton + ingest + lease/state → (2) scoring-plane reuse + assembler + finalizer → (3) harness + fault injector + comparator; the corpus builder runs parallel from day 1. Story priority: P1 = replay→report + comparator + fault suite; P2 = continuous_* logging + identity-from-(session_ts, chunk_num); P3 = repeatable regression suite. Key Entities = analyzer_sessions + analysis_segments; Success Criteria = G-1…G-7. A team may instead fold Phase 0+1 into one "shadow" feature — the boundary sits where output stops going to harness artifacts and starts going to continuous_shadow_runs on live traffic. Take the next free specs/NNN- at build time.

5. Phase 1 — Shadow (prod, silent)

The win is confidence, not latency — "the batch pipeline, live." Same CV activity-timeline pre-pass as batch (not L1 windows), so scores match by construction; the finer L1 timeline is Phase 3. The soak proves lease/fencing, 429 pacing, drain, and per-task segment identity in prod before Phase 2 bets the report on them.

Warning. The service must never write task_sessions.result_analysis in Phase 1. A non-placeholder entry trips the Gemini sentinel (task_analysis_runner/core.py:1626-1641): the batch run then skips download, ffmpeg, and Gemini and returns the shadow entry verbatim — the unproven pipeline silently becomes primary, and the finalize RPC could flip ANALYSIS_DONE before batch ran. Enforced by a canary assertion (R-1): the service refuses to construct an upsert_task_analysis_entry / finalize_task_session call in shadow mode. Shadow writes go to continuous_shadow_runs + S3 only.

5a. Scope and user stories

Deliverable: a parity dataset (≥ 200 real sessions scored twice, batch and shadow) plus a clean operational record — the entry evidence for the Phase 2 flip.

User stories:

• (P1) Score real prod sessions live, write only to shadow; a nightly EQ-1…EQ-6 dashboard decides when parity justifies the flip.
• (P1) Isolated key + rate limiter sized to the P3 quota, so shadow can never 429-starve batch or proctor.
• (P2) continuous_* ops expose lease/restart/429/drain; a deterministic ramp dial grows coverage without half-analyzing a session.
• (P3) Per-session Gemini cost tracked against P2-corrected pricing, validating the budget at prod mix.

5b. Build list and seams touched

Seams in existing code:

• TUS post-finish (tus.py:152-274) — fan-out gated on FF_CONTINUOUS_L1 + selection; self-copy / cover-video / {} response untouched; ≤ 250 ms so hook latency (0 fails / 23,372 calls, peak 1.4/s) can't regress.
• Scoring library — build-time COPY of airflow/dags/video_analysis/**; reuse run_v2_map_unit / run_v2_reduce (synthesis.py:932-1053) verbatim; CI path filter watches that dir for both images.
• Prod-state reads — read-only PostgREST embeds (position config, task blobs, screenshare_timeline); no task_sessions writes.
• Submit NOT touched — v2/task_sessions.py:482-488 (GITHUB) + :910-916 (ZIP) still trigger_dag(...); the /finalize seam is Phase 2.

5c. Data model and shared mechanisms

Three service-role tables (full DDL in the design doc; RLS-4, explicit FK ON DELETE, migrations via supabase migration new):

• analyzer_sessions — one row per tasksession_id; lease (claimed_by, lease_expires_at, heartbeat), lease_epoch, state machine, config_snapshot, breaker counters.
• analysis_segments — 20-min scoring unit, identity (tasksession_id, task_id, segment_index); MAP JSONB, status, lease_epoch, prompt_version, model, token_usage.
• continuous_shadow_runs — shadow result + EQ metrics per (tasksession_id, task_id); joined to task_sessions at ANALYSIS_DONE.

No chunk-ledger table (D8): chunk hooks are not durable — S3 is source of truth, reconciled by a 60 s S3 LIST sweeper over each instance's leased sessions. L1/L2 rows, session_digests, nudge/chat tables are Phase 3.

Per R-MULTITASK, identity is per (tasksession_id, task_id): segments close on 1200 s of that task's footage; a task switch closes the open segment early.

5d. Exit gate — Measurable Success Criteria

Advance to Phase 2 only when all hold (EQ metrics defined in the design doc's "Migration & validation" + Appendix D — that copy is authoritative):

5e. Soak, failure modes, kill switches

Watch during the soak week:

• continuous_* ops (Better Stack): segment_map_done, drain_start, shadow_finalize, coverage_gap, circuit_open, lease_reclaim, budget_warning.
• Nightly continuous_shadow_report: rolling EQ-1…EQ-6 → S3 markdown + Discord; join continuous_shadow_runs × task_sessions at ANALYSIS_DONE.
• Human + capacity: weekly hand-review of the EQ-3 flip list + EQ-5 citations; RPM/TPM per session vs P3 quota; per-session cost vs P2 pricing.
• Coverage: characterize the sub-90% population (crash-reload, stop/restart, stragglers) — what Phase 2 auto-fallback must absorb.

Kill switches (each fire-drilled once this phase; every switch leaves a working system — batch authors every report):

• Sentinel (R-1) — canary assertion + shadow-only write path, backed by a code-review checklist item.
• FF_CONTINUOUS_L1=false (K-1) — mirrored on FastAPI + service (shared/feature_flags.py:24-33); stops fan-out and all shadow work.
• CONTINUOUS_SHADOW_PCT / _POSITION_IDS — ramp dial; drop to 0 to quiesce shadow instantly, no redeploy.
• Gemini breaker (K-7) + concurrency clamp (K-8) — 429s pause launches with backoff, defer segments, alert; sessions past the clamp run pure batch.

5f. Dependencies, assumptions, spec-kit slicing

Dependencies:

• Phase 0 green (replay EQ-1…EQ-5 pass on ≥ 50-session corpus; fault-injection clean).
• P3 (blocking) — separate GCP project + GEMINI_API_KEY_CONTINUOUS + measured RPM/TPM quota; shadow ~2× Gemini load, unsafe without it.
• P2 — fixed GEMINI_FLASH_PRICING + timeline/tags tokens in cost_summary, so G7 cost is trustworthy.
• P4 — private ACL on traces/continuous/** (from Phase 0). P1/P5 are not Phase-1 deps.

Assumptions:

• Submit → DAG untouched; batch is sole author of every prod artifact.
• PROMPT_VERSION pinned identical (2.6.0) across batch + shadow all soak — any bump resets the EQ clock.
• Prod chunk keys/ordering match the documented shape (screensharesession_ prefix, per-task {i}_{task_id} folders); S3 doesn't delete chunks mid-soak.
• Prod volume is low (~1 concurrent Fargate), so ≥ 200 sessions may need the full ramp and run past one week — G1 needs both, whichever lands later.

Spec-kit slicing. One feature, folded into the Phase 0 "continuous scoring service — shadow" feature with a Phase-1 prod-wiring story cluster (fan-out, shadow store + writer, rate limiter, isolated key, selection, dashboards). Clean-cut alternative: a thin follow-on that depends-on Phase 0, boundary at offline mechanism vs prod wiring; the EQ gate is shared with Phase 0's replay. Near-serial: store + writer, then limiter + key, then dashboards — team of 1-2.

6. Phase 2 — Primary (report flip)

At a glance

Phase 2 ships latency, not accuracy: same CV activity-timeline pre-pass and same v2 MAP/REDUCE as batch (prompt 2.6.0, pinned identical), so scores are equivalent by construction — the parity Phase 1 measured.

Decision. result_analysis stays byte-identical (R-SHAPE) — no new keys, no schema_version bump. Timeline-fidelity/accuracy changes wait for Phase 3; scored-shape changes for Phase 5.

Decision. No separate fallback DAG. Submit always triggers the same tasksession_completion_fargate DAG with dag_run_id = client_submission_id; the Gemini sentinel (core.py:1626-1641) makes it a ~1-2 min no-op after a live finalize, or a full batch run otherwise. Fallback comes from not removing today's submit→DAG trigger.

(a) Scope

User stories: P1 faster report + guaranteed batch fallback + byte-identical shape; P2 one-flag revert, correct playback video; P3 reconciler re-triggers any session unscored after 20 min.

(b) Build list

(c) The finalize seam

Both submit endpoints call trigger_dag(…, dag_run_id=client_submission_id) today — …task_sessions.py:482-488 (GITHUB), :910-916 (ZIP). Phase 2 inserts the resolver in front; the batch branch is unchanged. E2B /submit stays untouched — it never triggers (2026-06-02 double-fire). Expiry keeps expiry-{tsid}-{tid}, on batch until Phase 4.

def resolve_analysis_trigger(tasksession_id) -> str:   # shared/feature_flags.py
    if not is_enabled("FF_CONTINUOUS_PRIMARY"): return "batch"
    if not service_was_live_consuming(tasksession_id): return "batch"  # nothing to drain
    return "continuous"

Finalize (async after the 202): eligibility + coverage ≥90% (else HANDOFF) → drain ≤120s → tail MAP + run_v2_reduce (synthesis.py:932-1053) → combine_v2_buckets (result_combiner.py:374-463) → core.update_supabase (core.py:2642-2878) → finalize_task_session RPC (core.py:2897-2899) → utkrusht_score (core.py:2948-2971) → DAG hop. Any failure/HANDOFF → identical trigger_dag, full batch. The hop's read_outcome rebuilds won from DB (task_analysis_fargate_dag.py:426-505), so cert (:180-209), notify, and recommend fire once — no side-effects duplicated.

Idempotency spine. One client_submission_id per (session, task), minted in FE localStorage (usePerTaskSubmit.ts:18-29), is the shared key across FE retries, service dedup, Airflow dag_run_id 409-as-success (airflow_utils.py:89-127), and the reconciler. Only other namespace: expiry-{tsid}-{tid}.

(d) Data model + shared mechanisms

No new tables. Reuses analyzer_sessions and analysis_segments from Phase 0/1 (DDL in the Data model section). Deltas are write targets: real result_analysis (byte-identical) plus score, utkrusht_verified_skills, screenshare_video, and a new pipeline_metadata.continuous block (analysis_source, window/segment config, coverage_pct) beside result_analysis, never inside it (R-SHAPE). Key Entities: that stamp + client_submission_id.

Mechanisms: two runners (load-bearing — /finalize imports v2 REDUCE + core.py finalize as a library; both images build-time-COPY airflow/dags/video_analysis/**, so batch/live never drift); lease + fencing (one finalize owner; racing batch arbitrated by RPC + sentinel); three stamps (window_index gates re-MAP, pipeline_metadata.continuous = run stamp, lease_epoch fences zombies); CAS light. Digest CAS fold is Phase 3.

(e) Exit gate — Measurable Success Criteria

Warning. No flip until R-MP4 and R-PROCTOR hold on 100% of shadow sessions. The sentinel skips before ffmpeg (core.py:1650-1698 runs after it), so a no-op hop will not build the combined MP4 — the service must produce screenshare_video itself via incremental -c copy concat at drain. Proctor concat has no sentinel, so proctor_video is rebuilt by the hop for free — verify it in shadow.

(f) Soak, failure modes, kill switches

Watch during the soak: - Reversed shadow: batch in shadow on a 10% sample for 4 weeks (roles reversed → continuous_shadow_runs); nightly continuous_shadow_report DAG compares and posts a Discord embed. - BetterStack continuous_*: continuous_drain_start, continuous_finalize, continuous_coverage_gap, continuous_circuit_open + per-stage latency_ms. - Alerts: fallback >5% daily → investigate, >15% → auto-page; any session unscored by T+45 → page; duplicate-run (R-9); Gemini-budget breach. - Distributions: submit→ANALYSIS_DONE percentiles, coverage histogram, cost/session at P2-corrected pricing vs the Google bill.

K-2 and K-5 are each fire-drilled once in early Phase 2. Retired risks: R-4 (playback/proctor → R-MP4/R-PROCTOR gate), R-5 (score/tags drift → library reuse), R-9 (triple-fire → idempotency spine).

(g) Dependencies, assumptions, spec-kit slicing

Depends on: Phase 1 gate green (EQ-1…EQ-6 over ≥200 sessions / 3 weeks — the parity proof is the entry condition; accuracy is not re-litigated); P5 blocking (playback MP4); Phase 0 fault-injection reused for the G4 drill; P2 cost fix carried forward. P1-P5 land in parallel; only P5 + the Phase 1 gate block Phase 2.

Assumptions: - Phase 1 proved continuous ≡ batch (same pinned prompt 2.6.0 + calculator). - Sentinel per core.py:1626-1641: any non-placeholder result_analysis → batch skips download/ffmpeg/Gemini, exits ~1-2 min. - client_submission_id reliably minted by FE (usePerTaskSubmit.ts:18-29); reconciler absorbs the best-effort task_submissions gap. - Fargate cap=1 is fine — the report is already live; notifications fire on the Realtime status change; only cert/postmortem/recommended lag (minutes-tolerant).

Spec-kit: one feature — "continuous scoring — primary + finalize seam." The seam is the spine; playback MP4 and reconciler are P2/P3 stories within it, not separate features. P5 is a standalone prereq PR before the spec. Key Entities is short (the pipeline_metadata.continuous stamp), so FRs concentrate on the seam contract, idempotency, and exit-gate SLOs. Team of 1-2, near-serial: P5 spike → playback + /finalize finalizer → resolver + reconciler → fire drills → soak.

7. Phase 3 — Awareness plane (Bar Raiser + chat)

At a glance

Highest-scrutiny phase: the system speaks to the candidate for the first time. A wrong nudge or leaked hint is the most visible failure the platform can make, so it ships last behind a hard gate.

Decision. Candidate-facing, gated twice. Pre-launch: ≥300 human-reviewed simulated nudges must show zero solution leakage through the guardrail. Then per-position (positions.nudges_enabled, forward-only) on a few friendly design-partner positions, watched for veto rate and quality. Never a silent backfill.

Decision. The report stays byte-identical (R-SHAPE). Nudges and chat reach recruiters via an addendum read path composing candidate_nudges + task_session_chat_messages + a pipeline_metadata.continuous block alongside result_analysis, not inside it. No new result_analysis keys, no schema_version bump, no 4th bucket. Coachability as a scored bucket is Phase 5.

7a. Scope

Value: a fairer, less lonely assessment for the candidate; a verbatim, auditable Bar Raiser transcript plus a coachability signal for the recruiter — no scored number touched. Mechanism detail is in the design doc; this owns build order, seams, gates.

7b. User stories (P1/P2/P3)

7c. Build list

7d. Seams touched (existing code)

• Chat send = first authenticated /v2 endpoint; wires the candidate-JWT TODO at fastapi_service/routers/v2/sessions.py:28. Next attaches the HttpOnly candidateLoginToken as a Bearer header, like the flask-proxy.
• Task screen: mount <BarRaiserChatDock/> beside ScreenShareDialog in TaskQuestion.tsx (after :1087) — task-only, inherits activeTaskId.
• Position flag read mirrors positions.proctor_disabled (ProctorTusRecorder.tsx:64-66; add field at src/types/Position.ts:86-87).
• Realtime: the browser Supabase client is already tuned for far-from-Mumbai candidates (timeout: 30_000, heartbeatIntervalMs: 25_000, client.ts:24-28). Per R-REALTIME the analyzer sends a service-role broadcast on chat:{tasksession_id} after each insert (not postgres_changes); history/reconnect uses the authed Next route.
• Outbox copies the WhatsApp inbound loop (notifications/core/inbound_listener.py, migration 20260517000001), re-keyed phone_number → tasksession_id.
• Scoring base blocks (prompts/v2/base_blocks.py, composed at pipeline.py:681-706) gain the 2.7.0 panel note; lands with the FE panel.
• P1 fills the dead {skills_to_be_checked} placeholder (v1/skill.py:46-47) into the awareness plane only — never scoring (R-AWARE-SCORING).

7e. Data model + shared mechanisms

Four service-role tables (build list above), L1/L2 rows added to the Phase-0 analysis_windows table, two columns (positions.nudges_enabled DEFAULT false, task_sessions.nudges_active). Identity per (tasksession_id, task_id) (R-MULTITASK). Each table: DAO + Pydantic, RLS-4, explicit FK ON DELETE, service-role; chat/nudge tables have no anon SELECT (R-REALTIME). Full DDL in the Data model section.

7f. Exit gate — Measurable Success Criteria

The gate's nudge caps (all config-driven, per the _resolve_max_concurrent_analyses precedent at task_analysis_fargate_dag.py:141-177):

Advance out of Phase 3 (per-position, then broadly) only when all hold:

7g. Soak, failure modes, kill switches

Watch: BetterStack continuous_* ops carry task_session_id + latency_ms per stage (l1, l2, digest, nudge_gate, nudge_decision, guardrail_veto, chat_reply, chat_veto, injection_suspected).

• Dashboards — nudge send rate + SILENT-reason mix; guardrail veto rate (the leakage tripwire); chat p50/p95 + policy_action mix; spend vs $2.50; L1/L2 coverage + freshness lag. Nudged vs un-nudged cohorts stay separable by report badge; the ≥300 corpus is re-scored on every prompt change.
• Fail-closed guardrail — deterministic lint + a separate Flash veto turn that sees only task title/outcomes + pending message + proposed reply (never session content, so it can't be socially engineered); any error drops the message. A lost nudge is recoverable; a leaked solution is not.
• Capability isolation — tasks.solutions is never selected into any awareness context (canary-string unit test). A perfect jailbreak leaks only what the candidate already has.
• Freshness/gap gates — SILENT (audited) if newest L2 is older than 2×L2 or coverage <60%; force SILENT if >40% gaps. Placeholders read "unknown," never "idle."
• Cost + degradation — at $2.50 or a 429/spend breaker trip: suspend nudges/chat → widen L1 → batch fallback; chat shows "your reviewer has stepped away," still persists (R-OPS).
• Never writes result_analysis — can't corrupt the report or trip the Gemini sentinel (R-IDLE).
• Kill switches (each fire-drilled once): FF_BAR_RAISER_NUDGES, FF_CANDIDATE_CHAT, positions.nudges_enabled, the Gemini 429/spend breaker, the concurrency clamp.

7h. Dependencies + assumptions

• P1 (position skill scopes) — blocking. The Bar Raiser can't judge "wrong direction for this position" without it; awareness plane only.
• Phases 0–2 complete — skeleton, lease/CAS/heartbeat, chunk ledger + 60s S3 sweeper, live scoring already primary.
• P3 (separate GCP + GEMINI_API_KEY_CONTINUOUS) — awareness calls off the batch/proctor quota bucket.
• Recommended first — TUS hook bearer + pre-create validation (F1.8); re-enable FE screenshare drain/crash recovery (§8.5) to shrink terminal-gap tails. Prompt 2.7.0 ships with the chat panel.
• Assumptions — Gemini ~20MB inline cap holds, keeping L1 at 60s single-turn on inline bytes (validated in Phase 0), and that fidelity is enough for nudge signal. Anon-key access is acceptable via service-role tables + broadcast + authed history route; per-candidate RLS hardening is deferred. Scoring keeps timeline_source=cv for byte-identical parity; the L1 swap (timeline_source=l1) is a gated accuracy change out of scope. Design-partner positions exist for opt-in; change_density struggle floors are calibrated from a prod histogram pre-launch; consent copy is legal-approved and the no-penalty invariant is stated to candidates.

7i. Spec-kit slicing note

Three features on a near-serial spine; the ≥300 zero-leak gate blocks both consumers from reaching a real candidate:

1. Awareness ingest — L1/L2 rows on analysis_windows, session_digests (CAS), flag columns, coverage observability. Soaks on the replay harness first.
2. Bar Raiser nudge engine — candidate_nudges, gate → judgment → guardrail, persona 1.0.0, nudge half of the addendum. Owns the ≥300 gate.
3. Candidate chat — task_session_chat_messages, analyzer_outbox, authed send endpoint + responder, dock, broadcast, chat half of the addendum.

Specify the shared seam (guardrail, answer-policy prompt, addendum read path) once in feature 2, consume in 3. Team-of-1–2 order: P1 → foundation → chat (reactive, safer) → nudge engine (proactive, high-scrutiny). P1 and P3 are small standalone PRs ahead of feature 1.

8. Data model across phases

The schema, sliced by phase so each phase's data-model.md cuts clean. The design doc holds the full DDL and ER diagram (Figure 5.1); this owns the ordering — which migration ships which table, with what key and FK action.

Decision. The schema ships in three migrations, one per schema-changing phase: session_analyzer_scoring_tables (Phase 0 — analyzer_sessions, analysis_windows, analysis_segments); continuous_shadow_runs (Phase 1); session_analyzer_awareness_tables (Phase 3 — session_digests, candidate_nudges, task_session_chat_messages, analyzer_outbox, plus the two flag columns). Phase 2 adds no schema — it is a write-path change at the finalize seam plus a pipeline_metadata.continuous JSONB stamp. All go through supabase migration new.

8.1 Master table: entity × phase

Every table keys on (tasksession_id, task_id). tasksession_id → task_sessions is ON DELETE CASCADE; task_id is a plain UUID, no FK. The FK column shows only deviations from that default.

Mechanisms per table: analyzer_sessions = lease + fencing (lease_epoch fences zombie writes); session_digests = CAS on version; windows/segments = index stamps (at-least-once → exactly-once).

8.2 Phase 0 — scoring-plane and lease tables

analyzer_sessions is the state machine and the lease. The lease fields are load-bearing from day one — the replay harness exercises lease-steal and stale-epoch fencing offline first.

CREATE TABLE analyzer_sessions (
  analyzer_session_id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
  tasksession_id  uuid NOT NULL REFERENCES task_sessions (tasksession_id) ON DELETE CASCADE,
  task_id         uuid NOT NULL,
  state           text NOT NULL DEFAULT 'IDLE',
    -- IDLE|LIVE|PAUSED|DRAINING|FINALIZING|DONE|ABANDONED|FAILED_FALLBACK|BATCH_ONLY
  active_session_prefix text,
  last_chunk_num int, last_chunk_at timestamptz,
  l1_next_window int NOT NULL DEFAULT 0,
  l2_next_window int NOT NULL DEFAULT 0,
  segment_next_index int NOT NULL DEFAULT 0,
  config  jsonb NOT NULL,   -- window knobs, frozen at claim
  context jsonb,            -- task blob + position scopes, fetched once (awareness plane only)
  claimed_by text,
  lease_epoch bigint NOT NULL DEFAULT 0,
  lease_expires_at timestamptz, heartbeat_at timestamptz,
  cb_429_count int NOT NULL DEFAULT 0, cb_window_start timestamptz,
  drain_started_at timestamptz,
  created_at timestamptz NOT NULL DEFAULT now(),
  updated_at timestamptz NOT NULL DEFAULT now(),
  UNIQUE (tasksession_id, task_id)
);

Per (session, task) because result_analysis is stamped with task_id and merged via upsert_task_analysis_entry (20260522131458); finalize_task_session counts distinct task_id (20260526170000). config freezes window knobs at claim so a mid-flight change cannot re-shard existing windows.

CREATE TABLE analysis_segments (
  tasksession_id uuid NOT NULL REFERENCES task_sessions (tasksession_id) ON DELETE CASCADE,
  task_id        uuid NOT NULL,
  segment_index  int NOT NULL,
  status         text NOT NULL DEFAULT 'PENDING',  -- PENDING|MAPPING|DONE|FAILED
  chunk_range    int4range, start_seconds int, end_seconds int,
  map_result     jsonb,             -- verbatim run_v2_map_unit output, REDUCE input
  segment_video_key text,           -- pre-encoded playback MP4
  lease_epoch bigint, attempts int NOT NULL DEFAULT 0,
  prompt_version text, token_usage jsonb, latency_ms int,
  created_at timestamptz NOT NULL DEFAULT now(),
  updated_at timestamptz NOT NULL DEFAULT now(),
  PRIMARY KEY (tasksession_id, task_id, segment_index)
);

analysis_windows (DDL in the design doc) is created here for its idempotency key, partial index, and coverage fields, but its L1/L2 rows are only written in Phase 3; through Phases 0-2 the scoring plane uses the CV activity-timeline pre-pass, not L1 windows.

Warning. window_index is floor((chunk_num − task_anchor) / 6) per (task_id, session_prefix), never floor(chunk_num / 6). The chunk counter is a page-global static that does not reset on a task switch (chunkStorage.ts:303-306), so a raw divisor would start task 2 mid-stream and corrupt every arithmetic treating window_index as per-task footage (segment boundaries, nudge lookback, the digest fold). task_anchor is a MIN over persisted rows, so a late or replayed event cannot shift it. Same for analysis_segments.

8.3 Phase 1 — the shadow table

One table. The live path must never write result_analysis until parity is proven — the batch sentinel treats any non-placeholder entry as "already done", so a wrong live write would defeat the fallback. The would-be report lands here and in S3 instead, with the captured batch result.

CREATE TABLE continuous_shadow_runs (
  shadow_run_id  uuid PRIMARY KEY DEFAULT gen_random_uuid(),
  tasksession_id uuid NOT NULL REFERENCES task_sessions (tasksession_id) ON DELETE CASCADE,
  task_id        uuid NOT NULL,
  client_submission_id text,             -- ties this run to the batch DAG run
  shadow_result  jsonb NOT NULL,         -- result_analysis entry the live path WOULD write
  pipeline_metadata jsonb NOT NULL,      -- continuous stamp: model, prompt_version, latency_ms, cost
  batch_result   jsonb,                  -- Fargate's actual entry (null until batch lands)
  parity         jsonb,                  -- EQ-gate metrics: score |Δ|, sub-dim agreement, citations
  segment_count  int,
  status         text NOT NULL DEFAULT 'SHADOW_FINALIZED',
    -- SHADOW_FINALIZED|BATCH_CAPTURED|COMPARED|COMPARE_FAILED
  finalized_at timestamptz NOT NULL DEFAULT now(),
  batch_captured_at timestamptz, compared_at timestamptz,
  created_at timestamptz NOT NULL DEFAULT now(),
  UNIQUE (tasksession_id, task_id)
);

shadow_result is byte-identical to what the live path would write, so the parity job diffs it against batch_result for EQ-1..6 (score median |Δ|, sub-dim agreement, recommended-flip rate, timeline recall, citations, T+10 SLO). The UNIQUE key makes finalize idempotent.

8.4 Phase 2 — no schema delta

No new table or column. The finalize seam writes the real result_analysis through the reused pipeline, plus a pipeline_metadata.continuous JSONB stamp. result_analysis stays byte-compatible (no new keys, no schema_version bump), so this phase's data-model.md is zero entities — only the write-path change and fallback contract.

8.5 Phase 3 — awareness-plane tables and flag columns

Four tables plus two flags in one migration (DDL authoritative in the design doc). Load-bearing constraints:

• session_digests — versioned with invariant version = length(applied_l2); CAS fold version = :expected AND NOT (applied_l2 @> :l2_id).
• candidate_nudges — audit ledger; every evaluation writes a row (suppressed included), keyed UNIQUE(…, evaluation_key) with evaluation_key = 'l2:{index}', one decision per L2 tick.
• task_session_chat_messages — task_id NOT NULL; partial-unique client_msg_id (only candidate-sent rows carry one); nudge_id → candidate_nudges ON DELETE SET NULL so the transcript outlives a ledger purge.
• analyzer_outbox — structural copy of the notifications outbox (20260320062639…:77-104), no FKs.

ALTER TABLE positions     ADD COLUMN nudges_enabled boolean NOT NULL DEFAULT false;
ALTER TABLE task_sessions ADD COLUMN nudges_active  boolean NOT NULL DEFAULT false;

Decision. nudges_active is stamped from positions.nudges_enabled at session creation, not read live — copying the positions.scoring_version seam (20260610000000 → 20260621054203). A recruiter toggling the position mid-assessment must not change a running candidate's experience; nudged and un-nudged cohorts must never mix silently; and the analyzer resolves from its own session row instead of joining positions every L2 tick.

8.6 Cross-phase conventions

Lift these into each phase's data-model.md. One convention, four parts: every new table keys on per-task identity (tasksession_id, task_id) in per-task footage seconds (never global chunk_num or wall-clock; a task switch closes the open window with a gap); gets an explicit FK ON DELETE (tasksession_id CASCADE, task_id no FK since task_sessions holds tasks as JSONB per _task_common.py:39-71, chat.nudge_id SET NULL, analyzer_outbox none); gets the RLS-4 service-role posture (enable RLS, no policies, revoke anon/authenticated, grant service_role; precedent task_competencies 20260604084807); and gets a DAO + Pydantic pair only if more than one service reads it.

Only candidate_nudges and task_session_chat_messages clear that DAO bar (both read by Flask at report time). The other six are analyzer-only and live service-local under session_analyzer/db/; the flag columns ride the existing task_sessions/positions models.

No browser reads any table directly — chat delivery is Supabase Realtime broadcast on chat:{tasksession_id} (no backing-table read); postgres_changes is avoided (the report_comments permissive-policy trap, 20260606090000…:1-21).

9. Cross-cutting: flags, observability, rollback

Every phase inherits this envelope — one flag set, the continuous_* logs, this rollback posture — pulled into its specify wholesale. Three invariants hold throughout: one author per report (service finalize seam or batch DAG, batch always the backstop, shape byte-compatible v2, I-5); report-safe by construction (any flip still yields a report for every session); drilled once (every switch fire-drilled before its phase exits soak).

9.1 Feature flags and kill switches

All env flags resolve through shared/feature_flags.py, mirrored into the service config the way FF_FARGATE_TASK_ANALYSIS is mirrored into airflow/dags/utils/feature_flags.py (I-7); the service, like Fargate, doesn't ship shared/.

Two ramp dials (not kill switches) sit alongside: CONTINUOUS_SHADOW_PCT / _POSITION_IDS (hash(tasksession_id) % 100, shadow-for-life) and CONTINUOUS_MIN_WINDOW_COVERAGE_PCT (default 90, the finalize / auto-fallback line). Design doc maps the table to switches K-1…K-9.

Warning. The shadow flag must never let the service write task_sessions.result_analysis. A non-placeholder entry trips the batch Gemini sentinel (I-4): the real batch run no-ops and returns the shadow entry verbatim, silently promoting unproven code. Phase 1 writes go to continuous_shadow_runs + S3 only; a canary assertion refuses to build an upsert_task_analysis_entry call in shadow mode.

9.2 Observability

No metrics infra today — logs (Better Stack, operation + task_session_id) plus pipeline_metadata JSONB (I-10). The service ships via LOGTAIL_SOURCE_TOKEN_* (runner.py:35-90) under the continuous_* namespace (_l1_window_done, _l2_coalesce, _drain_start/_shadow_finalize/_finalize, _coverage_gap/_circuit_open/_fallback, _nudge_decision/_chat_reply, _reconciler_fire), each with latency_ms + stamps. Nightly DAG continuous_shadow_report joins continuous_shadow_runs × task_sessions at ANALYSIS_DONE, computes EQ-1…EQ-6, writes s3://…/continuous_shadow/{date}.md, posts a Discord embed. Phase 2 reverses it — batch shadows a 10% sample for 4 weeks so EQ keeps running against the now-primary output.

What each soak watches (the advance signal):

"Report missing" triage extends /track-task: session stamp / pipeline_metadata.analysis_source → service finalize-job → reconciler log → DAG run (client_submission_id) → Fargate/CloudWatch.

9.3 Rollback

Decision — fallback-by-construction. Submit always triggers the batch DAG with dag_run_id=client_submission_id. The Gemini sentinel makes that a ~1–2 min no-op when the live path already finalized, or a full batch run when it didn't. The backstop comes from not removing the existing submit→DAG trigger — so reverting any phase is a flag flip, never a code migration or data repair.

Last resort for a report-less submit: the reconciler watchdog (10-min cadence, expiry-DAG precedent) finds a COMPLETED session past 20 min with a submitted task lacking a real result_analysis and no active DAG run, then triggers batch by client_submission_id. A duplicate run is cost, not corruption — that one idempotency spine collapses FE retries, service dedup, Airflow 409-dedup, and reconciler into safe overwrites.

9.4 Reliability posture and deployment

Decision — pace, don't discover. The service paces its Gemini call rate with a token bucket sized from the P3-measured RPM/TPM, on a separate GCP project + GEMINI_API_KEY_CONTINUOUS (blast-radius isolation from the batch/proctor key). It never discovers the ceiling by taking 429s; the breaker is the safety net, not the throttle.

• Derivable, not enqueued. Window readiness is recomputed from the ledger (analysis_chunks + analysis_windows), never a queue; any worker after any restart derives the same READY set. TUS hooks are fire-and-forget hints (≤250 ms, R-OPS); the 60 s S3 LIST sweeper is the guaranteed path.
• Checkpoint = digest version. Resume pointer is session_digests.version (monotonic, CAS-advanced, = len(applied_l2)); a restart rebuilds from the last window + digest, and lease_epoch fencing keeps zombie writes out.
• Paced backfill. A PARTIAL session gets a bounded backfill (≤ MAX_L1_BACKFILL_AT_FINALIZE=8 windows) from raw chunks before escalating; a DEGRADED session (coverage < 90%, gap > 5 min, or BATCH_ONLY) goes straight to whole-session batch.

Deployment. session_analyzer is a Coolify ARM64 service modeled on notifications/, its own GHCR image (ghcr.io/ngm9/) build-time-COPYing airflow/dags/video_analysis/ like the Fargate runner — one pipeline, two runners, zero forks. CI path filter watches airflow/dags/video_analysis/** for both images so logic can't drift. CI/CD: main→dev (udev-1), release→prod. Placement stays open for the phase specs (uprod-be-1 vs dedicated box vs ECS), but at 350 concurrent it's a dedicated ARM host — ~30–50 live sessions/instance (~85% LLM idle-wait), horizontal scale by lease-based ownership, no sticky routing.

10. Spec-kit handoff

Everything above is pre-spec input. Each phase runs its own specify → plan → tasks cycle into a specs/NNN-* dir — you never specify the whole plan at once. Phases don't map 1:1 to features: 0 and 1 merge (one codebase, one data model); Phase 3 splits into two independently-flaggable features. Confirm names and numbers at build time.

Phase → feature mapping

Decision. Each phase's exit gate becomes its feature's Measurable Success Criteria verbatim. The gates (EQ-1..6, the T+10 SLO, the ≥300-nudge bar) are testable thresholds so a specify prompt lifts them into spec.md unchanged.

Numbering. Backend specs → Utkrushta/specs/NNN-*; next free 022-025 in phase order (highest = 021). Phase-3 frontends are thin companion specs: recruiter recruiter-utkrusht/specs/021, candidate utkrushta-assessment/specs/001. P1-P5 are plain PRs or one-page specs, not phase features.

Definition of done (this planning doc)

• Every phase can start specify cold — no back-reference to a decision that was never made.
• Each phase section carries scope (operator value), a build list seeding FRs, a data-model delta naming Key Entities, a measurable exit gate → Success Criteria, and an explicit spec boundary.
• Data model across phases pins which phase owns which table; the Shared mechanisms primer lets specs cite CAS / lease + fencing / two-runners by name; this section fixes feature count and boundaries.