The library

Rendered from docs/code-map.md; the markdown file is the record.

HEARSAY code map

HEARSAY scores audio clips for synthetic-speech likelihood: CPU contract detectors (rule-based and learned), frozen-SSL probes (M1), an off-the-shelf anti-spoof scorer (M3) and a fine-tune lane (M5) each export fold-validated scores, which are fused into one score per test file and written as a TSV submission judged by normalized minDCF (C_FA = 4, C_MISS = 1, pi_synth = 0.3). Read first: docs/STATUS.md (one-page state), docs/architecture.md (component diagram, built / in-flight / planned tags), then this file for where things live and where to plug in. Every entry below cites file:line as reported by the finder pass on Sat Sep 26; re-check a line before editing.

Repo layout

src/hearsay/
  audio.py          decode/resample (ffmpeg -> 16 kHz mono float32), windows(), trim_silence()
  embed.py          frozen SSL embedding: v1 window path, v2 prepare_segment + embed_segment
  probe.py          M1 logistic probe on one SSL layer (load_embeddings, oof_scores, Probe)
  handcrafted.py    v3 75-feature extractor, band_limit (NSA 7.25 kHz wall), _crop, ctx for v4 families
  hc_v4.py          v4 feature families registry FAMILIES (lfcc, phase, cqcc, modulation, breath, jitter)
  compression.py    compression-forensics features + launder() codec round-trip
  trees.py          pure-numpy LightGBM inference and contributions (no lightgbm import at inference)
  metrics.py        EER, minDCF, cost_at, report(); the NSA cost constants
  submission.py     score_files, write_submission (TSV, never overwrites), append_log, preflight
  spectra.py        Spectra-AASIST loader and scorer (M0-era version only)
  m5_bundle.py, m5_data.py, m5_model.py    M5 fine-tune lane library
  detectors/        contract (base.py), shared learned base (_learned.py), handcrafted, compression,
                    container, enf, splice, engineered.py (single import point)
scripts/            CLIs: extract_/train_handcrafted, eval_bundle, extract_embeddings, train_probe,
                    make_probe_csv, make_folds, extend_folds, score_detector, extract_compression,
                    m5_*, spectra_direction, manifest_*, pull_mlaad, hash_audio, bench_latency,
                    make_constant_csv, inventory*
scripts/cloud/      launch.sh, box_chain.sh, reaper.sh, r2_guard.sh, teardown_check.sh, box_codecs.py
splits/             nsa_folds.csv (20,000 rows), nsa_folds_plus_asv19.csv (27,648), nsa_test_durations.csv (1,671)
tests/              pytest suite, 301 collected
docs/               STATUS.md, architecture.md, plan.md, nsa-challenge.md, handoffs/, reports/, specs/, consults/
models/ outputs/ weights/ data/ submissions/    gitignored artifacts and logs

Handcrafted features (D-track feature-engineering lane)

Where to add

• New feature family: src/hearsay/hc_v4.py:300-303, the FAMILIES dict literal. Write fn(ctx) -> dict[str, float] and add it under a new key (the key is the --families CLI name). ctx keys (built at src/hearsay/handcrafted.py:136-137): x (float32 audio), Z (complex STFT 512/160), S (power STFT), freqs, voiced (bool frame mask), rms_db, f0 (YIN track). Read Z/S from ctx; do not recompute the STFT.
• Column-name rules (scripts/train_handcrafted.py:46-48): unique, prefixed by family, not in META_COLS (path, label, generator, speaker, utt, source, filename, group, fold), not ending in _flag / _launder / _crop_s.
• Feature-content rules (tests/test_hc_v4.py): no content above 7000 Hz (FMAX), no absolute level, no duration or count features (means, stds, percentiles, rates only), offset-invariant (rel_tol 0.25 / abs_tol 0.05 on a shifted copy).
• scripts/train_handcrafted.py:51 FAMILY_PREFIXES: add name -> (prefix, ...). Without it, FAMILY_PREFIXES.get(fam, (fam,)) (used at lines 143-144) matches the family name as a literal column prefix, which is wrong for families like phase (gd_/pc_).
• src/hearsay/detectors/handcrafted.py LABELS (ends line 92): one plain-English entry per new column (or a dict-comprehension block like lfcc/cqcc/mfcc). Missing entries fall back to the raw column name at src/hearsay/detectors/_learned.py:109; the brief treats labels as required for judged evidence quality.
• src/hearsay/handcrafted.py:133-139 needs no change: the families tuple flows straight into FAMILIES[name](ctx).
• Add the family's expected key set to the EXPECTED dict in tests/test_hc_v4.py:33-44.

Invariants you must keep

• features() maps every non-finite value to 0.0 at src/hearsay/handcrafted.py:140; families need not self-guard.
• Unknown family name raises KeyError (src/hearsay/handcrafted.py:139; tests/test_hc_v4.py test_unknown_family_raises).
• With families=() the extractor returns exactly the 75 v3 columns (tests/test_hc_v4.py, len(features(x)) == len(V3)).
• feat_cols = columns that are not is_meta and not dropped, in file order; that order is saved as bundle['features'] and is the order _learned.py builds the inference vector in.
• At inference kw['families'] = tuple(b['families']) (src/hearsay/detectors/_learned.py:92-93), so the bundle recomputes exactly the families it was trained with (tests/test_handcrafted_detector.py:141).
• scripts/eval_bundle.py:53 assert not missing: the feature file must already contain every bundle['features'] column; eval_bundle never recomputes features from audio.
• Output .csv of extract_handcrafted = manifest columns + hc_crop_s + one column per feature; failures are flagged in hc_flag (line 73), never dropped as rows.

Gotchas

• hc_v4 is imported lazily inside features() only when families is non-empty (src/hearsay/handcrafted.py:134); importing hearsay.handcrafted alone does not pull it in. group_delay and cqcc import librosa/scipy inside the function body.
• --drop-columns (exact name or prefix*) is a training-time gate: a variant trains without re-extracting, per the v4 report's corpus-cue blocklist.
• eval_bundle's threshold comes from the bundle's own detector_scores inner_oof rows joined to splits/nsa_folds.csv labels (scripts/eval_bundle.py:59-63), not from the --features file.
• band_limit is defined at src/hearsay/handcrafted.py:43 (one finder cited 44; 43 is correct).

Engineered detectors (contract, rule-based, compression, tree evaluator)

Where to add

• New rule-based contract detector: copy the shape of src/hearsay/detectors/enf.py (123 lines): module docstring with rationale and score calibration, applies() returning True, run() memoizing one analyze(ctx.audio) via ctx.memo, DetectorResult built from named constants, then DETECTOR = X(); if NAME not in REGISTRY.names(): register(DETECTOR) at module bottom (enf.py:121-123, container.py:144-145, detectors/compression.py:65-66). Constraint: name must be unique or register raises ValueError (base.py:206). Without label coverage keep scores mild (enf uses 0.4/0.5/0.6, enf.py:9-11 and 32; splice uses 0.5/0.6, splice.py:33).
• New learned contract detector: subclass FeatureModelDetector (src/hearsay/detectors/learned.py:61-114) exactly as src/hearsay/detectors/compression.py does: define feature_fn (audio -> dict[str, float]), a LABELS dict, set name/prefix/kind_label/memo_key/labels/feature_fn, register at import. Bundle must contain features, kind ('logreg' or 'lgbm'), feature_stats ({name: {real_mean, real_std, auc}}), crop_mode, band_match, and model or trees_dump (_learned.py docstring lines 7-12). prefix must match models/<prefix><kind>_<stamp>/ (_learned.py:31-38).
• Register the new module in src/hearsay/detectors/engineered.py:16-23 (import line plus LEARNED or RULE_BASED at lines 18-19); otherwise tooling that only imports engineered misses it.
• New AI-tool or synthesis vocabulary: src/hearsay/detectors/container.py:30-41 tuples; matching is substring except 'tts' (word-boundary regex, lines 80-81).
• Training-time laundering: src/hearsay/compression.py launder():105 (mp3 or aac only, ValueError otherwise at line 110), driven by scripts/extract_compression.py on a random half of both real and spoof rows.

Invariants you must keep

• run() is only ever invoked through safe_run (base.py:163); it skips when applies() is False, and any exception, wrong type, name mismatch or non-ok status becomes status='error' with score NEUTRAL_SCORE = 0.5 (base.py:40).
• features values must be finite (base.py:104-105); DetectorResult.post_init (line 122) raises, never clips.
• safe_run wraps the result in dataclasses.replace (base.py:186), so a detector cannot keep mutating a returned features dict.
• Registry rejects duplicate names (base.py:205-206); names()/all_detectors() iterate sorted by name so fusion columns are stable.
• enf score is always in {0.4, 0.5, 0.6} (enf.py:32) and features include all analyze() keys (enf.py:118); splice score is always 0.5 or 0.6 (splice.py:33); classify_tags never raises and returns one of exactly three pairs.
• container routing features is_pcm_wav (container.py:119) and lossy (line 118) gate other detectors.
• hearsay.compression.features output is finite (compression.py:102); LAUNDER_CODECS weights MP3 3:1 over AAC (line 41).
• predict_proba is clipped away from 0/1 (_learned.py:96) before the logit.
• Trees.contrib + bias reproduces raw() exactly (tests/test_trees.py:32); raw()/predict_proba match real LightGBM within 1e-9 on tests/fixtures/lgbm_toy.json (tests/test_trees.py:22); no source or test file imports lightgbm (tests/test_trees.py:69).

Gotchas

• NEUTRAL_SCORE is a sentinel: fusion never feeds it in as a real score, it imputes the fold-local train mean plus a missing indicator (base.py:14-17).
• src/hearsay/trees.py exists because lightgbm and torch each ship libomp and loading both in one process fails (trees.py:4-9); do not reintroduce a direct lightgbm import at inference.
• splice floor_range_db is reported in features/evidence (splice.py:66-71, 108) but does not move the score (docstring lines 12-14).
• container scoring is rule-based on purpose: on training data the container is the label and the NSA test set is uniform PCM16/16 kHz (container.py:13-17).
• enf's mild scores are a stated limitation (no hum in training corpora, enf.py:6-11), not an oversight.
• ContainerDetector.run raises RuntimeError when ffprobe finds no audio stream; safe_run turns that into an error result.

M1 deep path (frozen SSL embedding -> logistic probe -> submission)

Where to add

• Decode args (resample rate etc.): src/hearsay/audio.py:27-32 only; every consumer goes through load_audio. Changing SR (src/hearsay/init.py:3) requires re-extracting all embeddings.
• A new embedding mode: add a field to the Probe dataclass (src/hearsay/probe.py:65-73) and a branch in scripts/make_probe_csv.py:61, which currently switches on probe.segment.
• prepare_segment band_match flag (src/hearsay/embed.py:80): callers that already band-limited (handcrafted._crop, src/hearsay/handcrafted.py:62) pass band_match=False. MAX_SEGMENT_S (embed.py:19) caps v2 segments; changing it invalidates probes trained under the old cap.
• Extra training corpora: scripts/extend_folds.py:34-40 builds group = source + ':' + (generator if spoof else speaker) and assigns fold ids '0'..'k-1' as strings, never 'holdout'. Verify a new corpus needs band matching or is already band-limited (src/hearsay/handcrafted.py:26-30) or the probe may learn the wall as a cue.
• Generalization check: scripts/train_probe.py:108-121 --stress loads a never-fit-on embedding set and reports minDCF/EER at its own threshold and at the train-OOF Bayes threshold (line 114); it never refits.
• Resumable extraction: scripts/extract_embeddings.py:81-86 skips existing shard_XXXXX.npz; rerun the same command to resume.

Invariants you must keep

• All train/test/live audio passes through load_audio (src/hearsay/audio.py:1-4); trim_silence never returns less than min_keep_s = 1.0 s (audio.py:106).
• embed_clip and the bulk window path produce identical features (tests/test_audio_and_submission.py:179).
• prepare_segment order is band -> trim -> crop -> cap (embed.py:82-85, 96-104); it never pads or tiles a short clip (tests/test_audio_and_submission.py:270). scripts/extract_embeddings.py and scripts/make_probe_csv.py must call it identically or train/test features diverge.
• load_embeddings asserts every manifest row is covered exactly once (src/hearsay/probe.py:34) and reorders by row (line 35); a partial extraction fails loudly.
• CV, layer selection and Platt fit touch only train (or non-holdout fold rows); val is scored once (scripts/train_probe.py:87-106); assert auc > 0.5 at line 89.
• With a fold file, oof_scores uses PredefinedSplit (src/hearsay/probe.py:58-59), never a fresh StratifiedGroupKFold.
• make_folds: every fold has >= --min-per-class per class (scripts/make_folds.py:69), no group straddles folds (line 71), output columns are exactly path,label,generator,speaker,source,group,fold (line 74). extend_folds: no path overlap with base (scripts/extend_folds.py:41), no group straddles folds (line 43), holdout count unchanged (line 48).
• write_submission never overwrites (src/hearsay/submission.py:85-86) and validates range, uniqueness and length.
• C_FA = 4.0, C_MISS = 1.0, PI_SYNTH = 0.3 (src/hearsay/metrics.py:29-31); scripts default --pi-synth to 0.3.

Gotchas

• windows() tiles short clips (src/hearsay/audio.py:82-83); prepare_segment never does. The same manifest extracted with and without --segment yields structurally different statistics.
• Two different per-row randomness schemes: crop lengths come from one shared RNG stream in test_duration_sampler (embed.py:76) drawn once per manifest row in order (scripts/extract_embeddings.py:70), while the crop offset uses default_rng(args.seed + r) (embed.py:102, extract_embeddings.py:90). Manifest row order changes crops. Any rescoring script must reproduce both.
• Resuming after changing --seed, --crop, --win-s or --max-windows silently mixes settings across shards (scripts/extract_embeddings.py:81-86, 134-136); delete stale shards or use a new --name.
• If extract_meta.json is missing, train_probe silently defaults probe.segment=False (scripts/train_probe.py:81-85).
• cv_groups (src/hearsay/probe.py:38) is used only on the non-fold path of train_probe; the --folds path uses the fold file's group column.
• The sidecar llr column is NaN for rows flagged decode_error or score_error (scripts/make_probe_csv.py:85-86); fb (line 74) is sigmoid(shift), the prior-only posterior, not 0.5 in general.
• band_limit's _FIR cache (src/hearsay/handcrafted.py:40) is built once per process; changing BAND_MATCH (line 39) needs a restart.
• make_folds documents known leakage limits (DiffSSD multi-speaker generators share cloned targets; LJ-voice generators share the LJ voice) at scripts/make_folds.py:9-11 and 77-78; they are reported, not silently fixed.
• src/hearsay/metrics.py:13-15 flags an open sponsor-formula ambiguity (P_FA weighting), unresolved.

M5 fine-tune lane (XLS-R 300M fine-tune)

Where to add

• Exclude an extra spoof generator family from a fold's training: src/hearsay/m5_data.py:36-40 FAMILY_EXCLUSIONS (fold -> substring tuples); must match that fold's validation generator families.
• Per-generator extra-spoof cap: scripts/m5_build_manifest.py:39 --extra-spoof-cap (default 1000).
• Bundle output location: scripts/m5_build_bundle.py:39 DEFAULT_OUT is a machine-specific path; override with --out.
• CPU test path: scripts/m5_train.py:218 --cpu-smoke runs the identical code on the TINY random-init config (src/hearsay/m5_model.py:53-57).
• Deployment cap: scripts/m5_score.py:58 --max-s (default DEPLOY_MAX_S = 8.0).
• ITW P_FA bar fallback: scripts/m5_assemble.py:119 --m1-itw-pfa (default 0.012); lines 187-188 prefer M1's own meta.json value.
• Watchdog timing: scripts/cloud/reaper.sh:11-12 DEADLINE / STALL_MIN env vars; NEXT wait: scripts/cloud/box_chain.sh:60-70 WAIT_MIN (default 45).

Invariants you must keep

• MAX_CLIP_S = 15.0 and PEAK = 0.999 (src/hearsay/m5_bundle.py:20-21).
• Fold-file shas pinned (src/hearsay/m5_data.py:28-29) and enforced by check_folds_file (line 55); In-the-Wild paths never enter the training manifest (lines 150-151); DEPLOY_MAX_S = 8.0 shared with M1 and every detector (line 44); crops in [3.0, 14.0] s (lines 42-43).
• keep_layers = 12, train_top = 12 by default (src/hearsay/m5_model.py:23-24); load_m5 refuses on any hash mismatch (lines 206-212).
• Bundle build: core and test rows are never dropped, a core decode error is FATAL (scripts/m5_build_bundle.py:172); extra decode-error fraction under --max-error-frac (default 0.005) or abort (lines 174-175); cross-scope PCM collisions drop the extra row and log dropped_extra_collisions.csv (lines 206-210); core/test overlap is reported in test_overlap.csv, never hidden (lines 211-213).
• Trainer: trains where CUDA is available and exits otherwise unless --cpu-smoke (scripts/m5_train.py:230); refuses on bundle tree-sha or XLS-R config-sha mismatch (lines 9-10); refuses if any trivial shortcut AUC exceeds --shortcut-max on its own training rows (shortcut_aucs, src/hearsay/m5_data.py:193); one crop length per batch (LengthMixer, m5_data.py:223-235); steps are wall-clock-fixed, never checkpoint-picked on validation.
• band_match is applied to every clip the model sees, after augmentation (src/hearsay/m5_data.py:264, scripts/m5_train.py:104).
• Assembler: len(oof) == len(inner) == 16142 (scripts/m5_assemble.py:147); holdout 3858 and test 1671 (lines 151-152); no partial stacking set: a missing fold model means no inner_oof rows and stackable=false (lines 133-137); the M1 bar is the newest models/m1_* whose meta.json train is a single NSA set with no comma (lines 41-48), M1b reported beside it and never gated on.
• Cloud: no unprovisioned instance is left running (scripts/cloud/launch.sh:62-63); all R2 paths are under HEARSAY_R2_PREFIX (scripts/cloud/r2_guard.sh:4); status and log are pushed to R2 on EXIT (scripts/cloud/box_chain.sh:16); the reaper never exits while a job is active (scripts/cloud/reaper.sh:50-55).

Gotchas

• scripts/m5_score.py flags decode errors per row (lines 36-38) rather than failing.
• deploy_transform (src/hearsay/m5_data.py:258) and bundle_transform (line 272) differ only in trim / band-limit order (tested to shift the boundary by at most 1 frame).
• The gate rule text (scripts/m5_assemble.py:212-214) names three conditions (holdout, pooled OOF, ITW P_FA) but only holdout_passed (line 208) is a computed boolean; the other two are separate fields a caller must AND itself.
• reaper.sh must run under caffeinate; Ctrl-C does not destroy instances (scripts/cloud/reaper.sh:4). teardown_check.sh destroys every instance on the account, not only M5 ones.
• m5_data.group_key (src/hearsay/m5_data.py:63) must stay identical to scripts/make_folds.py:group_key per its docstring; not diffed in the finder pass.

M3 Spectra-AASIST stream and shared validation/submission machinery

Where to add

• M3 extensions land in src/hearsay/spectra.py spectra_logits (lines 54-59): spec D4 asks for a pad_mode parameter; spec D2/D3 requires the input to go through hearsay.embed.prepare_segment before windowing, which the current file does not call.
• hearsay.metrics.by_group (spec D9) is to be copied verbatim from scripts/train_handcrafted.py into src/hearsay/metrics.py after report() (past line 106); not present yet.
• write_submission score_max (src/hearsay/submission.py:80) is the only knob if the score ceiling ever changes from [0, 1].
• Any new .claude/skills//SKILL.md or codex-.md rubric is pulled into every living-doc check automatically (tests/test_docs_consistency.py:22-23); it must state the pinned constants correctly and avoid banned words.

Invariants you must keep

• WIN = 64,600 samples, HOP = WIN // 2 (src/hearsay/spectra.py:26-27); synth_logit = logit_spoof - logit_bonafide and must increase with synthetic likelihood (line 62-63).
• Direction gate: auc < 0.5 or median_synth_spoof <= median_synth_bonafide is a hard failure (scripts/spectra_direction.py:88). Its Platt fit is diagnostic, marked provisional, and must never be fit on the NSA validation split or In-the-Wild (docstring lines 11-12).
• Submission format: TSV, header filename<TAB>cm-score, score in [0, 1], 0.0 = bona fide, 1.0 = synthetic (src/hearsay/submission.py:3-5). write_submission never overwrites (line 86) and re-reads the file to assert header, order and values (lines 107-109). LOG_COLUMNS order is fixed: timestamp, rung, validation_score, validation_score_clean_only, csv_path, notes (lines 29-31).
• score_files records fallback plus a flag ('decode_error', 'score_error:<Type>', 'nonfinite_score') for every failing file, guaranteeing one row per input (src/hearsay/submission.py:44).
• min_dcf at pi_synth = 0.3 is the sponsor-judged number (src/hearsay/metrics.py:19); reports lead with it, not EER. C_FA = 4.0, C_MISS = 1.0, PI_SYNTH = 0.3 (lines 29-31) are pinned by tests/test_docs_consistency.py:107, which also requires CLAUDE.md and docs/plan.md to contain the literal strings 'C_FA = 4' and 'π_synth = 0.3'.
• Living docs (CLAUDE.md, README.md, docs/plan.md, every .claude/skills//SKILL.md, the two codex-.md rubrics) may not spell out the comma-separated-values word (the TSV-format rule) outside the allowlist (tests/test_docs_consistency.py:124), may not state a conflicting prior (line 116), and may not contain dropped-scope vocabulary except on lines marked '(cut)', capped at MAX_CUT_LINES = 6 (lines 27, 72).
• docs/scoping.md and docs/master-doc.md must equal their content at git sha e1a1e88 plus exactly one banner line; the first handoff must be byte-identical (tests/test_docs_consistency.py:156).

Gotchas

• scripts/score_spectra.py and tests/test_spectra.py do not exist; git log on src/hearsay/spectra.py shows one real commit (0e2df3d, M0). The M3 spec describes planned work that has not landed.
• The m3val map left it unverified whether hearsay.audio.windows() repeat-pads short clips; the deep map confirms it tiles them (src/hearsay/audio.py:82-83).
• sponsor_min_dcf (src/hearsay/metrics.py:78) uses the sponsor's own constants and polarity (higher score = bona fide); it exists to catch a polarity mismatch with the sponsor's script, not as the primary metric.
• score_files swallows all scorer exceptions (src/hearsay/submission.py:60); check ScoredFiles.flags / n_flagged after scoring.
• bench_latency times only the backbone forward pass; pooling and head are excluded (docstring line 5).
• splits/nsa_folds_plus_asv19.csv (27,648 rows, 15,128 bonafide / 12,520 spoof) also exists; do not conflate it with the 20,000-row base file.
• MLAAD is gated with a non-commercial notice (scripts/pull_mlaad.py:3).

Documentation (docs/, CLAUDE.md, README.md)

Where to add

• A new lane's "where do I plug in" map: docs/handoffs/ (pattern: docs/handoffs/2026-09-26_feature-engineering-map.md). Results: docs/reports/. Run specs: docs/specs/. External consults: docs/consults/.
• Any completed AI-assisted work: CLAUDE.md:113-155 AI-use disclosure, which the rules require to be kept current through the weekend.
• Team ownership: CLAUDE.md:17-22.
• Constraints: CLAUDE.md, README.md, docs/plan.md and every SKILL.md are scanned by tests/test_docs_consistency.py (no spelled-out comma-separated-values word, no conflicting prior, no dropped-scope vocabulary, exact 'C_FA = 4' and 'π_synth = 0.3' strings).

Invariants you must keep

• Sources of truth: docs/plan.md for scope, submissions/log.csv and models/*/meta.json for numbers (architecture.md:1), docs/nsa-challenge.md for rules.
• docs/scoping.md, docs/master-doc.md and docs/handoffs/2026-09-25_first-two-hours-handoff.md are frozen at git sha e1a1e88 (tests/test_docs_consistency.py:24, 156).

Gotchas

• docs/STATUS.md and docs/architecture.md are snapshots, not auto-updated; commits ea65f73, 982aa11 and 8445095 (04:25-04:34) land at or after their timestamp.
• docs/reports/2026-09-26_m5-xlsr-finetune.md is intentionally a skeleton.

How-to recipes

(a) Add a feature family to the handcrafted detector

1. Write myfam(ctx) -> dict[str, float] in src/hearsay/hc_v4.py reading x/Z/S/freqs/voiced/rms_db/f0 from ctx; prefix every key with the family name; obey the naming and content rules above.
2. Register it in FAMILIES (src/hearsay/hc_v4.py:300-303).
3. Add its key set to EXPECTED in tests/test_hc_v4.py:33-44 and run uv run pytest tests/test_hc_v4.py -q (key names, finiteness, offset invariance, disjointness from v3).
4. Add 'myfam': ('myfam_',) to FAMILY_PREFIXES (scripts/train_handcrafted.py:51).
5. Add plain-English LABELS entries in src/hearsay/detectors/handcrafted.py (LABELS ends line 92); run uv run pytest tests/test_handcrafted_detector.py -q.
6. Extract: uv run python scripts/extract_handcrafted.py --manifest outputs/manifests/<m>.csv --name <name> --families lfcc,phase,cqcc,modulation,breath,jitter,myfam --workers 6 [--crop test --seed 0] (writes outputs/handcrafted/<name>.csv + .meta.json).
7. Train and gate: uv run python scripts/train_handcrafted.py --train <name> --folds splits/nsa_folds.csv --test <test_name> --out-name handcrafted_v4 [--drop-columns 'contrast0_mean,mfcc2_std*']; selection by inner CV only, holdout read once.
8. Stress: uv run python scripts/eval_bundle.py --bundle models/hc_lgbm_<stamp> --features outputs/handcrafted/<file>.csv --oof outputs/detector_scores/<out-name>.csv.
9. Record the gate result in docs/reports/2026-09-26_handcrafted-v4.md.

(b) Add a new contract detector and export it for fusion

1. Rule-based: copy src/hearsay/detectors/enf.py's shape (docstring with rationale and calibration, applies() True, run() memoizing analyze() via ctx.memo, named score constants, register guard at module bottom). Learned: subclass FeatureModelDetector as src/hearsay/detectors/compression.py does (feature_fn, LABELS, name/prefix/kind_label/memo_key), and train the bundle with scripts/train_handcrafted.py so it lands in models/<prefix><kind><stamp>/.
2. Import it in src/hearsay/detectors/engineered.py:16 and add it to LEARNED or RULE_BASED (lines 18-19).
3. Write a hermetic test in the pattern of tests/test_handcrafted_detector.py (toy bundles, ClipContext.from_array, contract B1-B9) and add it to tests/test_engineered_registry.py's expected set.
4. Run uv run pytest tests/test_detector_contract.py tests/test_engineered_registry.py tests/<new test> -q.
5. Export fold-validated scores: uv run python scripts/score_detector.py --detector <name> --folds splits/nsa_folds.csv --test-manifest outputs/manifests/nsa_test.csv --workers 6 (inner_oof / holdout / test splits under outputs/detector_scores/).

(c) Run the fold-validated gate for any detector

1. Fold file: splits/nsa_folds.csv (or splits/nsa_folds_plus_asv19.csv when the row set includes ASV19); never build fresh folds. Extend with training-only rows via scripts/extend_folds.py --base splits/nsa_folds.csv --extra <rows> --out <new file>.
2. Rule-based or any registered detector: uv run python scripts/score_detector.py --detector <name> --folds splits/nsa_folds.csv --test-manifest outputs/manifests/nsa_test.csv --workers 6.
3. Handcrafted / compression bundles: scripts/train_handcrafted.py --train <name> --folds splits/nsa_folds.csv --test <test_name> --out-name <out>; compression features first via uv run python scripts/extract_compression.py --manifest outputs/manifests/nsa_train_sample.csv --name nsa_train_sample --crop test --seed 0 --launder-frac 0.5 --workers 6.
4. M1 probe: scripts/train_probe.py --folds splits/nsa_folds.csv --train <embedding sets> [--stress <itw set>] (layer picked by argmin CV (min_dcf, eer), holdout scored once, assert auc > 0.5).
5. M5: scripts/m5_assemble.py checks 16142 / 3858 / 1671 row counts and compares against the newest NSA-only M1 bar.
6. Read minDCF at pi_synth = 0.3 first (hearsay.metrics.report), then EER; stress sets are read at the inner-OOF threshold (scripts/eval_bundle.py, scripts/train_probe.py --stress).

(d) Produce a TSV and log it

1. Rollback baseline: scripts/make_constant_csv.py --test-dir <dir> --manifest <m> --pi-synth 0.3 --out <path> --notes <text>; it runs preflight, score_files with a constant, write_submission and append_log with validation_score 1.0 (scripts/make_constant_csv.py:33-62).
2. M1 probe: scripts/make_probe_csv.py --probe models/m1_<...> --test-dir <dir> --manifest <m> --pi-synth 0.3 [--cost-shift] --val-mindcf <x> --val-eer <y> --notes <text>; preflight (submission.py:148) scores silence and a chord twice and asserts reproducibility before any real file.
3. write_submission (src/hearsay/submission.py:73) refuses to overwrite; pick a new path per attempt. It validates equal lengths, unique ids, finite scores in [0, 1] and re-reads the file.
4. append_log (src/hearsay/submission.py:113) appends one row to submissions/log.csv with the fixed LOG_COLUMNS; csv_path is stored repo-relative.
5. Check ScoredFiles.flags / n_flagged and the sidecar's flag column before trusting the TSV.

Tests: what pins what

Known gaps and stale docs

• docs/reports/2026-09-26_handcrafted-v4.md ends at line 34 with the placeholder "(filled in below from the full 20,000-clip run; four variants, all selected by inner CV only, holdout read once each.)" and nothing follows; the training-variant section is not written.
• No v4-trained bundle exists under models/: only hc_lgbm_20260926-0232 and three hc_logreg_* dirs, all with train='nsa_train_sample_v3'; outputs/detector_scores/ has handcrafted.csv, v1, _v2, _v3 but no handcrafted_v4.csv. outputs/handcrafted/ does contain nsa_test_v4.csv, nsa_train_sample_v4.csv and the hc_gate*.csv per-family gate files with sidecars.
• No speaker-embedding-drift detector exists anywhere in src/hearsay/detectors/: no stub, TODO or partial implementation.
• No Dockerfile exists yet for the M5/Docker deployment path; the inferred image file list is src/hearsay/m5_model.py, m5_data.py, audio.py, handcrafted.py, embed.py, metrics.py, scripts/m5_score.py, a saved model dir (backbone/, head.safetensors, m5_config.json, hashes.json) and pyproject.toml / uv.lock.
• The CPU-parity check in docs/specs/2026-09-26_m5-xlsr-finetune.md:106 (Spearman > 0.99, max |logit diff| < 0.05 on 50 clips) was not found implemented in scripts/m5_train.py, scripts/m5_score.py or any tests/test_m5*.py.
• scripts/m5_assemble.py describes a 3-condition gate (lines 212-214) but exposes holdout_passed, the pooled-OOF comparison and itw['passed'] as separate fields, not one combined boolean.
• scripts/score_spectra.py does not exist; src/hearsay/spectra.py lacks the M3 extensions (pad_mode, prepare_segment integration, direction check, crop plan, export helpers); hearsay.metrics.by_group is absent; the M3 spec's Results, Codex plan review and Audits sections are placeholders.
• docs/STATUS.md:44 claims "297 passing, 301 collected"; uv run pytest -q reports 301 passed, 301 collected.
• docs/STATUS.md:41 and docs/architecture.md (both stamped Sat Sep 26 ~04:40) describe M5 as in flight with no pilot; commits ea65f73, 982aa11 and 8445095 show the pipeline built, a pilot launched, an MLAAD probe A (cap 12%), an In-the-Wild P_FA gate in the assembler, and the gate bar changed to NSA-only M1 by content with M1b beside it.
• CLAUDE.md:117-126 AI-use disclosure lists work only through the D-track CPU chat; the M1 TSV submission and M1b addition (dba960c, 582ecee), the 7.2 kHz band-match fix (133e536) and consult findings (0ad7a30), the M3 plan/spec/handoff, the M5 pipeline and pilot (ea65f73, 982aa11, 8445095), the v4 scaffolding (4b644c9 through 096754d), the architecture diagrams (9288d73) and docs/consults/ have no entry.
• CLAUDE.md:17-22 team table rows for Teammate A/B/C are still "fill in".
• docs/handoffs/2026-09-26_feature-engineering-map.md:3 says a repo-wide code map is being generated at docs/code-map.md; this file fulfils that pointer.
• src/hearsay/metrics.py:13-15 flags an unresolved sponsor-formula ambiguity (P_FA weighting by P(attack)).
• m5_data.group_key (src/hearsay/m5_data.py:63) vs scripts/make_folds.py:group_key identity was not diffed.

Reading order

Feature-engineering teammate

1. docs/STATUS.md
2. docs/handoffs/2026-09-26_feature-engineering-map.md, then docs/handoffs/2026-09-26_handcrafted-v4-brief.md (section 3 "Where to plug in" is the recipe)
3. src/hearsay/handcrafted.py (features:72, ctx:136, preprocessing 43-68)
4. src/hearsay/hc_v4.py (FAMILIES:300 and the six family functions)
5. tests/test_hc_v4.py (the contract every family must satisfy)
6. scripts/extract_handcrafted.py (--families -> .csv + .meta.json)
7. scripts/train_handcrafted.py (META_COLS/META_SUFFIXES, FAMILY_PREFIXES, --drop-columns, bundle contents)
8. src/hearsay/detectors/_learned.py (run:88, _evidence:102) and src/hearsay/detectors/handcrafted.py (LABELS:21)
9. tests/test_handcrafted_detector.py (hermetic contract-test pattern)
10. docs/reports/2026-09-26_cpu-detectors.md, then docs/reports/2026-09-26_handcrafted-v4.md
11. scripts/eval_bundle.py once a family is real

Docker teammate

1. README.md for the target CLI contract (docker run --network none -v <test_dir>:/data:ro -v <out_dir>:/out hearsay)
2. CLAUDE.md Conventions (offline-only, 16 kHz mono, no hosted API)
3. docs/plan.md Docker section; docs/STATUS.md:43 currently lists Docker as not started and unowned, verify before starting
4. docs/architecture.md for loader -> orchestrator -> detectors -> fusion -> TSV writer
5. src/hearsay/detectors/base.py (Detector:149, safe_run:163, Registry:195) and src/hearsay/submission.py (score_files:44, write_submission:73, append_log:113)
6. src/hearsay/audio.py (load_audio:22) and src/hearsay/m5_data.py (deploy_transform:258, DEPLOY_MAX_S:44), scripts/m5_score.py (score_paths:30) for the CPU inference path
7. src/hearsay/trees.py (why lightgbm is never imported at inference)
8. docs/STATUS.md Data table for what is mounted read-only, baked in (weights) or excluded (train-only data)