Changelog

All notable changes to this repository. The format follows Keep a Changelog; phases refer to spec §12 (sitemap-and-content-directory.md).

[Unreleased] — Phase 5 begins: the eegloop core (2026-09-20)

Phase 5 — neurofeedback and BCI on consumer headsets — is proposed in site/notes/proposal-phase5-consumer-nf-bci.md and gates on eight author decisions listed there. The library’s synthetic and replay paths gate on none of them, so the library starts first.

Added

  • loop/eegloop 0.1.0, the core. A second installable package beside pipelines/eegpipe, built the same way and deliberately not part of it: eegpipe is a batch pipeline that depends on MNE; this is a loop over blocks of a stream that depends on numpy and scipy. It ports the real-time section of notebooks/_shared/helpers_l7.py — ring buffer, causal FIR with state carried across blocks, the latency budget, the loopback probe — into something installable, multichannel and unit-tested (47 tests, no network, no device). The notebook helpers are not edited; a parity test holds the two to 1e-12, and under CI that import is hard so the guard cannot skip itself away.
  • Two rules the design review forced into the step contract. Quality runs first, on the raw block, because a gate placed after the band-pass cannot see line noise, muscle or a flat channel — the chain would otherwise build L7.5’s “the notch deletes the diagnostic” into its own fixed order. And latency is summed only where it is exact: a linear-phase FIR’s (N − 1)/2 is a row in the budget; a smoother’s delay is not one number and is listed as measured, filled by the probe, never added into the total.
  • A library CI job mirroring the pipelines one, with a step that fails if the parity test was skipped.
  • The spec amendment that makes Phase 5 real (author decisions of 2026-09-20): §12 gains Phase 5; §6 gains L7.10–L7.16 with L7.9 kept reserved for §13 item 23; §7 gains path-consumer-nf-bci; §0 rule 6 and §10.6 now admit the author’s own consumer recordings for this track under conditions — a registry entry, a licence, a public home and a consent statement (§13 item 25) — with the IN_HOUSE block staying until all four exist; §13 items 3, 16 and 23 answered, items 25–27 added. site/CONTRACTS.md gains the Phase 5 addendum: ownership, the six device-naming rules, the datasets clause, and the rule that no live output is ever an answer key.
  • loop/recordings/ is gitignored: the author’s own headset recordings exercise the device path in development and never enter the repository, an asset, or a page (§10.6).
  • Phase B: sources and steps. (The proposal’s ScheduledMarkers shipped as ListMarkers; KeyboardMarkers follows in the post-approval fixes.) A synthetic stream with planted answers — alpha bursts, frontal blinks, a dropped-sample gap that shows in the timestamps, clock drift, a flicker component, cues with an evoked response and a lateralised power change, electrode pops, a flat channel — and a truth dict naming every one; replay of arrays, .npz, .csv, the site’s own .bin+sidecar assets and MNE formats, paced on the wall clock or fast, never straddling a gap; cues on the source clock. The quality gate runs first, on the raw block, with detectors.py’s criteria cited, and a three-state verdict with a hold; reference, frozen spatial filters, envelopes and features each say whether their delay is exact or measured. 83 tests, no network, no device.
  • Phase C: the neurofeedback loop, the protocol, the session, the command line. Lesson L7.3’s five decisions are five objects — SignalSpec (what the signal is, exactly; it writes the sentence CRED-nf item 4 asks for), FixedBaseline/AdaptiveBaseline (each with a note on what it does to a learning claim), ContinuousMapping/ThresholdReward, ShamPolicy (the four modes helpers_l7 names, sealed into the log as a token only the seed unblinds; yoked replays a donor session block for block) — and FeedbackLoop runs them with the display frozen or zeroed on a gated block, never fed a cleaned guess, and the processing row of the budget measured rather than stated. A Protocol file names every decision and is validated all at once in eegpipe’s message format; SessionLog writes session.json, events.jsonl, signal.npz and protocol-resolved.json with every string scrubbed of absolute paths, and SessionReader opens them with numpy alone; Recorder writes the stream in spec §4.5’s .bin+sidecar so a learner’s recording opens exactly as a shipped asset does, its sidecar marked license: private. eegloop run | validate | budget | probe | versions; two shipped protocols (synthetic; the latency widget’s own eyes-closed trace); examples/alpha_bar.py as the smallest application. analysis.learning_test is a sign-flip permutation test across sessions beside naive_trend, helpers_l7.within_session_trend kept and labelled invalid; crednf_report marks each of the six items satisfied, not satisfiable alone, or unsatisfied, with why. 113 tests, no network, no device.
  • Phase D: the BCI loop — calibrate once, freeze, apply. cut_epochs and EpochCutter cut the same window to the sample, offline and online, on a stated clock (sample or timestamps), and drop — never patch — an epoch over a gap or a gated stretch. fit_frozen fits csp_lda, riemann_ts or xdawn_lda (scikit-learn pipelines mirroring helpers_l7’s families; CSP through pyriemann so the decode extra needs no MNE, a stated divergence) with folds in cue order, never shuffled, prints the chance band (chance_interval = helpers_l6.chance_band, held by a parity test), then freezes the pipeline into arrays — spatial filters, tangent-space reference, scaler, classifier — that replay it in numpy to 1e-6, checked before returning; FrozenDecoder.save writes an .npz with nothing pickled and the loop runs the arrays. StreamingPosterior + DwellDecision (sliding) and a cue-locked mode, BCILoop walking calibrate → fit → apply and scoring decisions against the cues it can see; SSVEPDetector by canonical correlation. A bci block in the protocol; two shipped protocols (imagery on the planted lateralised alpha, an oddball on the planted P300); examples/cue_switch.py. On the synthetic answers: imagery decodes at 100 % offline and ≥ 85 % online after a temporal split, the four-channel P300 at AUC ≈ 0.7, and CCA finds the planted 12 and 15 Hz flickers. 127 tests, no network, no device.
  • Two things the synthetic stream made measurable, kept as lessons. The stream’s timestamps run 200 ppm fast against its sample clock while its cues are on the sample clock, so a cutter that aligns by timestamps lands the last epoch five samples early — the first parity test failed on exactly that, and EpochCutter now takes the clock as a parameter and a test asserts the shift. And the standing 10 Hz alpha correlates with a 10 Hz reference in every window, flicker or not, so an SSVEP detector at an alpha-band frequency reports alpha; SSVEP_NOTE says so where the detector is described.
  • Phase F, started: L7.10 and L7.11 as drafts (content-L7c, notebooks-L7c, data-p5, integrator). L7.10 What a four-channel headband measures with nb-7-10-headband (the two geometries as facts from the board table; the nearest cap sites to TP9/TP10 computed, not asserted — T9/T10, then TP7/TP8; the occipitotemporal replica on twelve ds-eegbci subjects, 12/12 with an eyes-closed alpha peak; the bandwidth edge measured; an on-device notch measured as a loss of diagnostics; the survives-which-geometry matrix). L7.11 Getting a stream with nb-7-11-stream (one interface for replay, synthetic and device; the block contract; the rate measured against the rate claimed; a planted loss counted and verified to the sample; drift in milliseconds; a session recorded in the site’s own format and read back). L7.12 Signal quality you can act on live with nb-7-12-quality (the gate’s criteria cited; sensitivity on planted blinks 27/27, pops, a flat channel and a mains line; three states and a hold; the replica’s unusable fraction, median 0.053 with one popping subject at 1.000, printed as a table; the online gate against the offline detector on the same minute, 11 of 18 blinks; one consumer export’s edge, hole and EQ.* columns by range request; ICA at rank 4 and 64 measured — and the lesson rewritten to say what the numbers say). Three new pitfalls: pf-contact-is-not-signal and pf-adaptive-threshold-moving-target (figures from make_figures_p5.py, synthetic and labelled so) and pf-vendor-derived-features (a real figure: one ds-areeg export’s raw 8–12 Hz power beside its vendor quality column); pf-dropped-samples promoted to Level 7. common.DATASETS gains ds-areeg from the directory so the figure writers can cite it. All three lessons ship status: draft; every keyed number is cited to its notebook cell. check-content learns the objective verb “open” — and, once --strict-drafts was run over the finished track, “combine”, “assemble”, “structure” and “package”; with those the full published gate passes over all twelve Phase 5 drafts with 0 errors.
  • Phase F, finished: L7.13–L7.16 and the path, as drafts. L7.13 The feedback signal with nb-7-13-feedback (three derivations of band power per block and what each adds to the budget; smoothing quantified as measured latency by the loopback probe, 616 ms against 510 exact; the baseline from calibration and what an adaptive threshold does to a learning claim; the channels of a montage combined with the combination stated; w-latency-budget feedback mode embedded). L7.14 A protocol that can fail with nb-7-14-protocol (the naive trend reproduces nb-7-3’s 8 of 12 through the library to 10⁻¹⁶; the four sham modes; the valid sign-flip test and its power table — and the yoked minutes do rise over a minute, so the claim is the contrast, not the null; the sealed token; crednf_report). L7.15 A first BCI on four channels with nb-7-15-bci (the chance band held to Level 6’s helper; eyes closed against eyes open on the occipitotemporal replica with a time split, median 0.79, pooled 0.76 on 144, the leaky shuffled split 0.96 beside it; the P300 at 16/8/4 channels on one dry-headset subject, 0.944/0.940/0.846 AUC; SSVEP by CCA on the planted flicker with the alpha caveat measured; a blink switch labelled EOG; BCILoop block by block). L7.16 Build the application with nb-7-16-application (the two example applications run as programs on the shipped four-channel asset and the synthetic stream; the session.json fields the rubric reads; a pip-project shape with a replay entry point; the probe within one block of the arithmetic — 503.1 against 503.1 ms; the gate over 4 of 4 planted artifact windows; four sham modes sealed and unblinded; CRED-nf five of six with the pre-registration committed and twelve sessions tested; the EO/EC switch on the replica, 44 of 54 pooled over the nine subjects whose decoder was fitted — three never calibrated because the gate held their stream unusable, stated as the gate doing its job; the hardware-run record with every value TODO(confirm)). The path paths/consumer-nf-bci.md: fifteen lessons in the proposal’s order, 1000 minutes, seven skipped prerequisites. Three glossary entries (sham-feedback, pre-registration, chance-band); pf-decoding-leakage, pf-site-device-confound, pf-vendor-derived-features and pf-dropped-samples link the new lessons. Every page ships status: draft.
  • Library, for L7.16. The eo-ec synthetic scenario (alternating 6-s eyes-closed / eyes-open periods, a cue at each boundary, a planted alpha burst on every closed period — the one two-class state both montage classes can decode); configs/eo-ec-synthetic.yaml and configs/alpha-up-oc4-replay.yaml (the alpha loop over the shipped four-channel asset: one asset, two consumers); examples/eo_ec_switch.py (a lamp that closing the eyes turns on) and examples/blink_switch.py (an EOG switch, labelled as such); tests/test_examples.py runs the three examples as programs and asserts the rubric’s file-checkable items — the “L7.16 CI job” inside the existing library job (142 tests collected on a runner, 143 with the hardware-marked one); the hardware-run record template in loop/HARDWARE.md.
  • Promoted (2026-09-21): the author approved the Phase 5 drafts. L7.10–L7.16, path-consumer-nf-bci, the three new pitfalls and the ds-cognitive-states-students stub page go status: published — twelve pages, after --strict-drafts had applied the full published gate to them with 0 errors. The TODO(confirm) markers in the key comments stay, under the author’s 2026-09-19 ruling that disclosed gaps ship; the notebooks keep their “draft — for expert review” header line as every other notebook does.
  • eegloop is public: MIT, and a standalone repository (2026-09-21). Spec §13 item 4 answered — the package is MIT (loop/LICENSE, copyright the author; pyproject points at the file) — and it is published at neurokinetikz/eegloop as a one-way git subtree mirror of loop/: the monorepo stays the source of truth and .github/workflows/sync-eegloop.yml pushes the split on every change to loop/ (it skips itself until the deploy-key secret exists). So that a clone is a working package, loop/assets/ now mirrors the five shipped files the replay protocols and the latency test read — alpha-ec, oc4-ec and traces.json — byte for byte from the site’s copies, with their ODC-By attribution restated in assets/README.md; tests/test_assets_mirror.py holds the two copies equal whenever the site is beside the package. The README’s quick start runs from the package root and names the monorepo’s prefix once. Verified by cloning the public repository into an empty directory: 143 tests (7 skipping, the ones that cross-check against the course’s notebook helpers), the four-channel replay protocol running at its stated 610 ms budget.
  • After the author’s approval: the Phase 5 gap audit and its fixes (2026-09-21). Four auditors read the proposal, the CONTRACTS addendum and the spec against the repository and reported 78 candidate gaps; a fresh reader tried to refute each — 60 confirmed (50 actionable, 10 the author’s), 18 refuted (site/notes/integration-phase5.md). The actionable ones are closed in five commits: content and notes (the path’s skipped prerequisites; a mains line, not a hole, on the vendor-features figure; links, pointers and key comments; the lab pages; the stub page’s verified fields); the library (the budget’s decision section, with_probe, KeyboardMarkers, the driver’s marker row, the README’s protocol schema, nine tests including measured reward and decision latencies, serial-number checks in both renderers); the figures (a railed channel; the real replayed-sessions panel; the manifest re-registered); the feedback mode’s filter-Hilbert derivation (the spec’s “envelope stage via the existing hilbert.ts”, held to the library’s reference to 2e-5 µV); the notebooks (helpers_l7.py appended with import_eegloop, the replica and ds-areeg loaders; the own-recording pass in all seven; all re-executed with every keyed number unchanged); the three other Zenodo records read further and entered as directory-only stubs; the spec’s §8 row, §9.2 (34), §10.4 and §14 brought up to what shipped; track notes library.md, widget-latency.md §8 and integration-phase5.md.
  • data-p5-licences: the Zenodo record read from the record. Zenodo 20089290 enters data/directory.yaml as ds-cognitive-states-students (an id from the record’s title, per the proposal) with its licence verified in three places — cc-by-4.0 in the record metadata, the legalcode link on the landing page, and nothing inside the archive (59 CSVs, no LICENSE or README) — so it derives allowed, class A; the draft dataset page is generated for it alone and the registry entry stays the author’s (§10.1 rule 3). Two findings the record does not state: the timestamps are written to the millisecond, so the rate must be counted (256.02 Hz over one file’s span; 3,885 intervals read as gaps that are not), and the data dictionary describes a metadata_subjects.csv the archive does not contain. Whether the app’s notch was on is TODO(confirm). One 3.9-MB file was read and deleted; the three other Zenodo records the proposal listed (22093536, 8429740, 10371068) were read at the metadata level — all three cc-by-4.0, open — and stay out of the directory until the author picks one. site/notes/data-p5-licences.md.
  • Phase E: the headset source. BrainFlowSource(board_key) — the driver behind the same Source interface as a replayed file, StreamInfo built from the driver’s board descriptor at runtime with any disagreement against the board table recorded, blocks split at every loss the package counter shows (modulus inferred at the first wrap; the increment histogram kept for the report), timestamps rebased to the session. BOARDS is the one table that names a device (muse-2, muse-s, muse-s-athena, brainbit; the deprecated *_BLED ids refused by name); loop/HARDWARE.md holds the per-device facts with verified dates and the list of what a report must still settle. Pairing details reach the driver from the environment only, so no protocol, log, sidecar or report can carry one. eegloop check — the acceptance report on any source: rate measured against rate claimed, drops, timestamp structure (the packet-burst signature of arrival-time stamping), per-channel DC, spread, flatness, the mains line at 50 and 60 Hz, the bandwidth edge (an on-device low-pass shows as a cliff), gate-label prevalence; verdicts in first_look_checks’ names; eegloop devices. Tested on a fake board with the driver’s interface — a planted five-packet loss, a wrapping counter, packet-identical stamps — and on the synthetic scenarios; pytest -m hardware runs the one test that needs a headset, only with EEGLOOP_HARDWARE=<key>. The LSL source waits on its binding decision and says so.
  • One disagreement found and recorded, not reconciled. The repository has three things called a “pop”: detectors.py’s sustained step, helpers.detect_artifacts’s sample-to-sample jump, and eegpipe.synthetic’s 20-ms transient. The first test of the gate against the synthetic stream failed on exactly that: the generator planted the third, the gate looked for the first. The gate now fires on either of the first two and the generator plants what the gate’s criterion means; loop/README.md says so.

Changed

  • The gate’s verdict: suspect is fed back, unusable is closed. The first whole-session run froze every block: the un-notched synthetic stream shows a mains line, line-noise marked every channel suspect, and the gate counted only good channels toward its minimum. A visible mains line is the normal state of a recording and the band-pass removes it, so suspect channels now count as usable and the block is fed back carrying the label (gate_state is in signal.npz); only an unusable channel, or too few usable ones, closes the gate.
  • A pop claim needs a neighbour. On a one-channel stream the “that its neighbours do not share” half of both pop criteria was vacuously true, and the shipped eyes-closed trace — 280-µV alpha waves at 160 Hz, clearing the 100-µV jump threshold on their own — drew six pop closures. A pop is a local event; with no other channel its locality is untestable, so the gate makes no pop claim and describe() says so, as it already did for blinks without a frontal channel.
  • The inverted sham inverts about the calibration baseline, the centre that exists when the value is shown; helpers_l7.sham_feedback inverts about the whole-session mean, which needs the future. Recorded in feedback/sham.py, not reconciled; the notebook that compares them prints both.

Fixed

  • eegloop.session.Recorder wrote a block-interleaved file. Each block’s channels × samples chunk was appended in turn, which no reader of the §4.5 layout (all of channel 0, then channel 1, …) understands; the Phase C round-trip test compared the file with itself and passed. nb-7-11’s record-then-replay comparison found it (a 389 µV maximum difference). The recorder now buffers the blocks and writes the file channel-major at close() (about 15 MB an hour for four channels at 256 Hz, stated in its docstring), and the test compares the read-back samples with the source’s.
  • eegloop check’s rate row read a known loss as a slow clock. The rate measured from the timestamps now counts the samples a detected gap removed as elapsed samples, so the drops row reports the loss and the rate row reports the clock: on the synthetic gaps scenario it reads the planted 200 ppm of drift (0.02 %) instead of 0.23 %.

Known gaps

  • The library’s synthetic and replay paths are complete through Phase E; the headset path is built and tested against a fake board, and every per-device fact HARDWARE.md marks TODO(confirm) waits on an eegloop check report from the author’s own headsets. Emotiv and Neurosity routes wait on spec §13 item 6; LSL on its binding. The content and notebook tracks (L7.10–L7.16 and the path) are written and executed, all status: draft for the author’s review; site/notes/content-L7c.md and notebooks-L7c.md list what each notebook found that the proposal had guessed differently. The four Zenodo records are verified class A on their records’ statements (site/notes/data-p5-licences.md; one archive unopened, one unread beyond its readme) but nothing derives from any of them until the author adds a registry entry; no script exists that could. Motor imagery is not available on either consumer montage the course names (no C3/C4); the imagery protocol exists to show the loop’s shape on a planted answer, and says so in its own header.
  • The lsl extra is undeclared until the binding is chosen at a named release (mne-lsl pulls MNE; pylsl needs liblsl).

[Unreleased] — All 161 pages published (2026-09-19)

The author reviewed every page and promoted the lot. status: review no longer appears anywhere in the content; 161 pages are published and the status badge is gone from the site.

Changed

  • TODO(confirm) no longer blocks publication, by the author’s ruling. §5.3 made a marker a publication blocker, which assumed the only way to avoid shipping an unverified claim is to withhold the page carrying it — the wrong trade when the page is otherwise reviewed, since it hides a whole lesson to avoid admitting a footnote. Two neighbouring rules were the same shape (an exercise with no answer key, a notebook a page names before it exists) and now share one disclosed() policy in check-content. What unites them is that the page already tells the reader: the marker is literal in the prose, the exercise says “No answer key yet” and declines to grade, and the notebook card carries a “notebook not yet indexed” badge with its buttons disabled. They remain reported as warnings. --strict-todo restores the original gate.
  • A checker bug, found by promoting. The rule meant to keep a published lesson’s notebook runnable read the lesson’s datasets: list — what the lesson discusses — rather than what the notebook downloads. It fired on L5.4, L5.5 and L5.6 for naming ds-fsaverage, which they name precisely because its licence blocks it, while their notebooks download ds-lemon or nothing. It would equally have missed a notebook fetching a closed dataset its lesson never listed. It now reads notebooks/index.json.
  • /start/ and /about/ were out of date and are corrected. /start/ still told readers that only three lessons existed and the rest were hidden stubs. /about/ still called the site name, domain and repository undecided.

Added (analytics)

  • Plausible analytics, at the author’s request, in the <head> of every page. It is the site’s only third-party request — no cookies, no cross-site identifier, nothing to consent to. /about/’s privacy section names it rather than claiming the site talks to nobody, and says that a content blocker stops it with no loss of function. Note that this makes “no analytics”, stated in the Phase 0 decisions in README.md, historical rather than current.

Added

  • TodoNote. Publishing removed the badge that used to explain the markers, which would have left TODO(confirm) sitting in prose marked finished with nothing saying what it meant. Each page now counts its own markers and says. On lessons, capstones, labs, pitfalls and paths — 103 pages; dataset pages already had their own note.

Fixed

  • The pipelines CI job, which had never passed. 17 failures and 52 errors all reduced to one undeclared package: pipelines/pyproject.toml never listed scikit-learn, and MNE implements method='fastica' through it. It passed locally throughout, because this machine has scikit-learn installed for the notebooks — which is how a missing declaration hides, being present for an unrelated reason everywhere except the one environment that installs only what is declared.

Known gaps

  • A second cache that invents faults. After 161 content files changed at once, the build reported Duplicate id "…" found for collections containing no duplicate; clearing .astro produced a clean build from identical sources. That is the second cache here to do this (the first was node_modules/.vite, twice). npm run dev:clean now clears both and build:clean joins it. Reproduce against a clean build before believing a strange symptom.
  • The two item banks are still algorithmic. The page review does not cover them: 67 drill items and 189 scroller annotations remain unreviewed, and scripts/apply-label-review.py can never write expert without a verdict.

[Unreleased] — Deployed to eeg.neurokinetikz.com (2026-09-19)

§13 items 1 and 3 are answered. The site is live at https://eeg.neurokinetikz.com/, published from this repository by .github/workflows/deploy.yml on every push to main.

Added

  • Deployment. deploy.yml stopped being a placeholder: it renders the notebooks, builds, runs Pagefind, asserts every notebook fragment exists, and publishes to GitHub Pages. HTTPS is enforced.
  • A sitemap and robots.txt. Neither could exist while site was a placeholder, because a sitemap needs an absolute origin to write into <loc>. 233 URLs. It lists what the build emits, which includes the 161 pages still at status: review — they are reachable, so they are listed. That is a different question from the feed’s, which carries published items only; the sitemap answers “what is reachable” and the feed answers “what is finished”.

Changed

  • A custom domain serves at its own root, so there is no base path. This is the decision with the longest reach in the repository: 466 internal links are root-absolute, and they are correct only because the site is served at /. Publishing at a bare …github.io/eeg/ URL instead would require a base and a rewrite of every one of them. A base-path implementation was written and then reverted when the domain was chosen.
  • The domain is configured in the repository’s Pages settings, not by site/public/CNAME. actions/deploy-pages does not read a CNAME file — a fact worth recording because the file’s presence suggests otherwise. It is kept so the setting survives redeploys.
  • Commit authorship rewritten to GitHub’s users.noreply alias, which GitHub’s email-privacy setting requires (it rejects the push otherwise, GH007). refs/original/ is retained locally as a backup.

Known gaps

  • “Open in Colab” stays hidden. The repository is private and the published site is public, which GitHub Pro permits, but Colab cannot read a private repository. REPO_IS_PUBLIC in site/src/lib/site/config.ts is the single switch that turns the buttons on for all 59 notebook cards if the repository is ever made public.

[Unreleased] — Phase 4, Level 7 and polish (2026-09-18)

Built by eight tracks in two waves. This completes §12: every phase of the build plan is done.

Added

  • Lessons all eight Level 7 electives and C7, the final capstone. Every level of the curriculum now has a body: 56 lessons, 8 capstones, 167 checkable exercises.
  • Widgets w-latency-budget and the sleep mode of w-raw-scroller — 26 widgets, the complete §8 catalog. The latency widget decomposes a real-time budget into filter group delay, buffer and processing rather than printing a total, and makes the zero-phase point concrete: asking for zero phase in a live loop costs a look-ahead of N−1 samples, and run per block it returns a negative delay, an output ahead of its input.
  • Notebooks 7 more, 59 in all, each executed with its outputs stored.
  • Site a /cite page assembling what the catalog already records; verified “In other tools” sidebars for every level; and the first accessibility audit, run against the built output in both themes.

Changed

  • Two dataset licences verified from primary sources, and a third found wrong in the catalog. ds-sleep-edf qualifies (ODC-By 1.0, derivative databases expressly covered). ds-bci-iv-2a does not: it is CC BY-ND, so its lesson may download, compute and publish benchmark tables but may ship nothing derived from the signal — the community summary of “open with attribution” is wrong on the decisive point. And ds-mpeng was recorded under its descriptor paper’s licence rather than the data’s: the paper is CC BY, the data are CC BY-NC, downstream of consent given for non-commercial research only. Nothing had ever derived from it. The registry fix is §10.11 item 0.
  • derive_snippets refuses no-derivatives licences explicitly. It returned no for CC-BY-ND-4.0 only because that spelling is absent from the permissive list — the right answer for the wrong reason, and correcting an apparent typo would have opened it silently.
  • “Expert” meant two different things. A sleep hypnogram scored by the recording’s own technologist is genuinely expert, but §4.5’s promotion rule — an annotated view leaves draft when every item is expert — means the author reviewed it. A third party’s scoring would have satisfied a gate that exists for the author’s judgement. An expert label must now carry reviewed_at or source.
  • Accessibility. Nine classes of failure fixed, the largest being 1,868 scrollable regions unreachable by keyboard. That remedy had to be remedied: the first version used a landmark role, so a notebook page acquired dozens of identically-named landmarks and a previously-silent rule began failing. Caught by re-measuring after the change. Two rounds of target-size failures, the second only visible once the first was fixed.
  • Exercise states read as what they are. An unfilled exercise advertised “Accepted within ±0”, which it could not honour since it declines to grade until its notebook runs. Three states now: a tolerance, an exact answer required, or no key yet.
  • The two group-contrast capstones contradicted each other on subset size, thirty per group against ten to twenty. Both now use the tighter figure and both name the ambiguity: §11’s number is written for a single-cohort capstone and the binding constraint is the ten-minute runtime.

Known gaps

  • Author review of every draft, label and answer key; all 161 content pages remain status: review, and the two Phase 0 item banks (67 drill items, 195 scroller annotations) are still unreviewed. The review tool is built: cd site && REVIEW_TOOL=1 npm run dev.
  • §13 items 1 and 3 (site name and domain; repository name) still block deploy, canonical URLs and the Colab buttons — the only disabled control left on 59 notebook cards. ds-mne-sample’s licence is a third open question; answering it unblocks a real head model, L5.4’s original exercise, L5.5, L5.6 and part of C5.
  • ds-srm’s EDF headers declare no unit, so every amplitude reads 10⁶ too large, and the dataset is self-consistent about it. mne-bids-pipeline runs on it, succeeds, and writes a report in which every microvolt is wrong. Recorded as a caveat; only one notebook loads it and no asset derives from it.
  • moabb’s default download channel for ds-bci-iv-2a is not the one whose licence was verified. Both notebooks pin the verified provider; whether the default republishes under the same terms is TODO(confirm).
  • Two figures skipped deliberately — no licence-clear dataset holds a marked epileptiform discharge or a scanner artifact, and simulating either would fabricate what those lessons teach people to recognise. L7.7 ships with no widget, no notebook and no figure.
  • No compact CNN in L7.1 (braindecode/torch deliberately absent); a filter-bank CSP stands in and says what it does not answer.
  • TFCE ships in neither cluster widget.

[Unreleased] — Phase 3, Levels 4–6 complete (2026-09-18)

Built by sixteen tracks in two waves against the Phase 3 addendum of site/CONTRACTS.md.

Added

  • Lessons all seven Level 4 (time-frequency and oscillations), all seven Level 5 (connectivity and spatial analysis) and all six Level 6 (inference and rigor) as full drafts, with C4, C5 and C6. Checkable exercises rise from 65 to 136; every one in Levels 0–6 has a filled key whose comment states the subject, the parameters, the tolerance and the reason the tolerance is what it is.
  • Widgets w-evoked-vs-induced, w-phase-clock, w-wavelet-explorer, w-tf-baseline-explorer, w-burst-detector, w-volume-conduction-sim, w-csp-explorer, w-garden-of-forking-paths, plus the forward mode on w-dipole-to-scalp and the tf mode on w-cluster-permutation-viz — 25 widgets in all. registry.ts is now generated rather than transcribed.
  • Notebooks 22 more (nb-4-1 … nb-6-5 and four capstones), 52 in total, each executed with its outputs stored, plus helpers_l4/l5/l6.py. statsmodels, scikit-learn and mne-connectivity pinned; bycycle optional with a documented fallback.
  • Site progress export and import (plan-then-apply, seven typed refusal codes, a refusal leaves storage byte-identical); “In other tools” sidebars for Levels 0–3 with every claim verified against EEGLAB 2026.0.0 and FieldTrip 20251218; the statistics thread wired across nine lessons; a dev-only review surface for the two Phase 0 item banks with an applier that can never mark an item expert without a verdict.
  • Tooling scripts/merge-manifest.py (parallel data tracks write manifest parts), scripts/gen-widget-registry.py, scripts/apply-label-review.py.

Changed

  • Two dataset licences failed the §10.7 gate and no boundary-element head model ships. ds-fsaverage is settled and does not qualify: its licence covers data as well as software and permits derivatives only by propagating the whole agreement onto every copy. Every convenient source is silent — the copy MNE ships contains no licence file, the hosting node returns no record, and MNE’s dataset documentation names none — so a check of those three would have concluded there was nothing to worry about. ds-mne-sample is genuinely contested and is a new §13 decision: its own documentation restricts use to familiarisation, its download channel carries nothing, a public mirror declares CC0 while dropping the restriction sentence, and the archive bundles fsaverage. Unlike ERP CORE there is no strictest-reading compromise, because “familiarisation only” cannot be complied with by being stricter. Consequently §8’s “precomputed BEM maps” and §6 L5.4’s “sphere vs BEM” exercise are not possible. What ships is two concentric sphere models, one shell against four, flagged is_bem: false with a disclosure the widget prints verbatim, and L5.4 now asks “one shell versus four — what does the skull do?”. Recorded as a deviation from the spec.
  • §6’s phase-locking positive control does not work, and the lesson said a failing pipeline is broken. Over 30 recordings the paired test — stimulus against silence within each recording, each normalised by its own neighbourhood — gives +0.259 dB, t(29) = 0.33, p = .745; power at the nominal frequency is 0.586× its own neighbourhood and none of the 30 reaches 2×. The archive names the phase “Fixed Auditory Stimulus” and states no rate; the rate was this site’s inference. L4.5 now reports the measurement as its lesson and uses two controls that do work. data/directory.yaml carries the finding and a question for the author.
  • Share-alike now reaches the reader. Seventeen ERP CORE sidecars named the licence without marking themselves share-alike and three carried no attribution; two different attribution strings were in use. Every asset now carries the complete one, sixteen pages render the obligation and the credit, and check-content rejects a sidecar that names a share-alike licence without both.
  • An unfilled exercise was grading answers. A null key coerced to zero against a default tolerance of zero, so a learner typing 0 was told they were correct. All four checkable types now decline to grade and say why; the rule lives in a tested module.
  • The content checker gained three rules: every array whose entries claim a label_source is validated (a sidecar was shipping a value the spec does not allow), share-alike assets must carry their attribution, and scripts/scrub-notebooks.py --check is a CI step alongside a new job that runs the pipelines tests.

Known gaps

  • Author review of every Phase 3 draft, label and answer key; all 161 content pages remain status: draft.
  • ds-mne-sample’s licence is a new §13 question. Answering it unblocks a real boundary-element model, §6’s original L5.4 exercise, L5.5’s inverse comparison, L5.6’s connectome and a quarter of C5.
  • nb-5-7 takes 19 minutes and breaks the §11 ten-minute budget; 9 seconds of that is compute and the rest is one host serving at a twentieth of the speed of the other two. Shrinking its subject survey would delete the selection-effect disclosure L5.7 turns on. The author decides which to keep.
  • §6 words L4.4’s exercise as a peak where the shipped key is a window mean; the prompt is unambiguous as written but the intent is the author’s to confirm.
  • TFCE ships in neither cluster widget: it needs its own null distribution and did not fit the budget. Both say so rather than relabelling what they do have.
  • ex-6-2 as §6 words it has no separable answer; it should ask for standard errors.
  • The Level 4 and 5 answer keys disagree with their notebooks in three places, each with the cause found and both numbers printed: two skull-effect figures differ because the widget evaluates at its nearest stored grid point and the notebook at the exact position, and one coherence noise estimate differs by a single draw.

[Unreleased] — Phase 2, Levels 2–3 complete (2026-09-18)

Built by twelve parallel tracks against the Phase 2 addendum of site/CONTRACTS.md. The tracks were interrupted twice by a session limit and finished from the state on disk rather than restarted, so the repository history for this phase is five commits rather than one.

Added

  • Lessons all eight Level 2 lessons (L2.1 loading and BIDS, L2.2 bad channels, L2.3 re-referencing, L2.4 filter choices, L2.5 artifact rejection, L2.6 ICA, L2.7 ASR/SSP and alternatives, L2.8 the pipeline) and all seven Level 3 lessons (L3.1 epoching and baseline, L3.2 the ERP and its components, L3.3 measuring ERPs, L3.4 topographies, L3.5 SNR and trial counts, L3.6 single-trial approaches, L3.7 statistics for ERPs) as full drafts; every checkable exercise in Levels 0–3 now has an answer key with its subject, channel, window and tolerance recorded beside it.
  • Widgets w-bad-channel-detective, w-threshold-tuner, w-ica-component-gallery (a seeded 20-component drill with a confusion table), w-reference-explorer (waveform and topography modes), w-epoch-builder, w-erp-averager, w-measurement-explorer, w-cluster-permutation-viz — 17 widgets in total, each with folder tests and a lab page; registry.ts regenerated.
  • pipelines/ the eegpipe package: the canonical step order as code (load → montage → bad channels → filter → interpolate → re-reference → ICA → epoch → reject), PipelineConfig from YAML, a run log that records a failure as a row rather than raising, HTML QC reports, version pinning and seeding, a CLI, three configs (erpcore-p3, eegbci, synthetic) and 123 tests. A subject that fails does not stop the cohort.
  • Notebooks nb-2-1 … nb-2-8, nb-3-1 … nb-3-7, and the capstones nb-c2-clean-pipeline and nb-c3-replicate-erp-core — 17 more, 30 in total, all executed with outputs stored; _shared/helpers_l2.py and _shared/helpers_l3.py; pyprep, mne-bids, autoreject and pandas pinned, with mne-icalabel (plus onnxruntime) and asrpy as optional packages that each degrade to a documented fallback.
  • Data extract_p2_widgets.py, make_ica_gallery.py, make_topomap_matrices.py, make_cluster_fixtures.py, make_figures_p2.py, fetch_erpcore.py; the manifest is now 157 records and 43.4 MB, with an asset kind taxonomy (timeseries, matrix, activation, spectrum, index, figure, json) so a topography matrix is no longer validated as if it were a µV time series.
  • Pitfalls 31 with full bodies, up from 15.
  • Paths /paths/erp, /paths/oscillations, /paths/bci, /paths/realtime.
  • Tooling scripts/scrub-notebooks.py (rewrites machine-specific absolute paths out of executed notebooks, in outputs as well as source; --check for CI) and scripts/merge-notebook-index.py.

Changed

  • ERP CORE’s licence is recorded as CC BY-SA 4.0 (spec §13 item 15, answered 2026-09-18). The licence is contested at source and three real statements disagree: the LICENSE file shipped with the data says CC BY-SA 4.0, dataset_description.json says CC0, and the OSF node thsqg record says CC BY 4.0. Spec §10.7 makes the most restrictive reading govern. Derived assets ship, each carrying CC BY-SA 4.0 and the attribution the LICENSE file asks for; share-alike binds anything derived from these data. data/directory.yaml gained license_status and license_decision, and both build_dataset_pages.py and check-content.ts now gate share-alike and contested licences on an explicit decision, so the ruling opened this dataset alone and left ds-hbn at snippets: no.
  • eegpipe.run.scrub_paths rewrites absolute paths out of a stored traceback, so a run log and the QC report built from it can be handed to someone else.
  • w-cluster-permutation-viz ships channel_adjacency, the 78-edge Delaunay neighbour list from the montage, so the browser re-clusters over the same neighbourhood the shipped null distribution was built on instead of falling back to MNE’s array lattice.
  • w-ica-component-gallery names, in the end-of-session summary only, the classes its drill offers that the loaded decomposition contains no example of. ICLabel found no cardiac and no single-electrode component in these three subjects, so two of the seven buttons were never correct and nothing said so.
  • Wall-clock test budgets are a regression guard, not a benchmark: bestOf(n, …) against regressionCeiling(expectedMs) with 8× headroom (EEG_PERF_FACTOR to override), after four timing assertions failed under a load average of about 50.
  • data/scripts/common.py reads the ERP CORE facts from data/directory.yaml at run time instead of holding a copy, which is what let two tracks write two different licences.

Known gaps

  • Author review of every Phase 2 draft, label and answer key; label_source is algorithmic throughout and all 161 content pages remain status: draft.
  • ex-2-7-snr-asr: asrpy 0.0.8 and the documented NumPy method disagree about what a cutoff of 20 SD means — 79 % of the signal RMS replaced against 17 % — and a reviewer must settle which behaviour the published key quotes.
  • ex-3-5-minimum-trials rests on an SME ≤ 1 µV threshold that is a course decision, not a literature value.
  • ICA does not converge for 9 of 10 subjects at max_iter: 500; the run log records the flag rather than failing, which is correct, but a cohort that flags nine in ten deserves an author’s eye.
  • steps.filter.ica_copy builds its ICA copy at 1–30 Hz while nb-2-6-ica and w-ica-component-gallery fit at 1–100 Hz. The difference is deliberate and each says so, but a component index is comparable within a source, not across.
  • FULL_COHORT = True in the capstones has not been executed (a further ~1.2 GB of download).
  • The data/downloads/erpcore cache was deleted after the tracks released it; data/scripts/fetch_erpcore.py repopulates it.

[Unreleased] — Phase 1, Levels 0–1 complete (2026-09-17)

Built by nine parallel tracks against the Phase 1 addendum of site/CONTRACTS.md and integrated the same day.

Added

  • Lessons L0.1, L0.2, L0.3, L0.6, L1.1, L1.2, L1.3, L1.4, L1.6, L1.7 as full drafts (every §4.1 section; answer keys computed or derived from the notebooks, TODO(confirm) where the author must confirm); Level 0/1 index bodies trimmed to prose.
  • Widgets w-sampling-explorer (hardware/math), w-montage-explorer, w-dipole-to-scalp (intro; analytic homogeneous-sphere potentials validated against MNE to < 1 %), w-build-a-signal, w-welch-explorer (welch/window), w-aperiodic-explorer (fit/compare), with folder tests and lab pages; registry.ts lists all nine.
  • Data data/scripts/extract_p1_widgets.py, make_montage_positions.py, make_dipole_fixtures.py, make_figures.py; assets for the six widgets (EEGMMIDB, Iowa PD; specparam fits for 12 subjects; 339-electrode positions from MNE’s standard_1005; dipole fixtures from MNE’s sphere model) and 13 figures under site/public/figures/; manifest now 109 records including JSON and figure kinds.
  • Pitfalls full bodies for pf-trigger-offsets, pf-dropped-samples, pf-bridged-electrodes, pf-site-device-confound, pf-group-demographic-confound, pf-aliasing-on-downsample, pf-zero-padding-resolution; Phase 0 pitfalls wired to real Example figures.
  • Notebooks nb-0-2-montages, nb-0-3-first-load, nb-0-6-first-look-report, nb-1-1-resampling, nb-1-2-fft, nb-1-3-psd, nb-1-6-line-noise, nb-1-7-specparam, capstone scaffolds nb-c0-recording-report, nb-c1-spectral-fingerprint; _shared/helpers_l1.py; index.json merged from index-parts/ (13 notebooks); specparam==2.0.0rc4 and edfio pinned.
  • Site Pagefind search (⌘K modal, /search, drafts excluded from the index unless SHOW_DRAFTS=1), /feed.xml (published entries only), resilient Figure with sidecar provenance, capstone-aware /notebooks, “used on this site” filter on /datasets; lab sidebars no longer duplicate body sections.
  • Validation check-content.ts: manifest path_roots, purely synthetic JSON/figure products, draft gate for notebook references, wiki-link grep limited to prose (not .py or notebook code cells).

Known gaps

  • Author review of all Phase 1 drafts, labels and answer keys; dataset pages are not promoted.
  • w-montage-explorer, w-dipole-to-scalp, w-welch-explorer, w-aperiodic-explorer ship generated placeholder screenshots until replaced by browser captures.
  • L0.1’s three-panel resolution-ladder figure (scalp vs intracranial vs rodent) is not generated: the intracranial and rodent sources were not downloaded in this phase.
  • Two psds.json fits (S004, S009 eyes-closed) re-evaluate below their stated R² (double-alpha decompositions); the aperiodic widget reads peak_params as summed heights.

[Unreleased] — Phase 0, vertical slice (2026-09-17)

Built in parallel by ten agents against site/CONTRACTS.md and integrated the same day (build, unit tests, content validation, headless-browser smoke test and Lighthouse all pass; see README.md). The author’s review is pending. Every lesson, lab and dataset page ships status: draft.

Added

  • Site scaffold — Astro 5 with content collections and MDX, Svelte 5 islands, uPlot; design tokens and global styles; layouts and routes for /, /start, /curriculum/…, /labs/…, /pitfalls/…, /datasets/…, /notebooks, /paths/…, /glossary, /about, /changelog, /404.
  • Content model — schemas for lessons, levels, capstones, labs, pitfalls, datasets, paths, glossary, reading and pages (site/src/content.config.ts, spec §5.2).
  • UI components — WidgetFrame, ExerciseBox, PitfallBox, NotebookCard, Callout, Figure, Cite, LessonNav, OtherTools, LevelProgress, LadderGraphic, ProgressTracker; localStorage progress store.
  • DSP library — site/src/lib/dsp/ (FFT, windowed-sinc FIR, Butterworth IIR / SOS, filtfilt, Welch) tested against SciPy fixtures generated by data/scripts/make_dsp_fixtures.py.
  • P0 widgets — w-raw-scroller, w-spot-the-artifact, w-filter-sandbox with READMEs and lab pages.
  • Data pipeline — data/scripts/ extraction scripts for the three widgets, data/manifest.json with provenance and checksums, scrubbed catalog snapshot (data/catalog/) and generated dataset pages.
  • Content — draft lessons L0.4, L0.5, L1.5; frontmatter stubs for every other lesson, widget, pitfall, dataset, path and glossary ID in the spec; reading-list seed (verified: false throughout).
  • Notebooks — nb-0-4-browse, nb-0-5-artifact-atlas, nb-1-5-filters, shared helpers, pinned requirements, notebooks/index.json.
  • Validation — scripts/check-content.ts implementing spec §5.3, the §10.7 snippet gate and the §10.10 private-path grep, with --warn-only, --strict-drafts and --verbose.
  • CI — .github/workflows/build.yml (build, test, validate, upload dist), notebooks.yml (weekly execution with nbclient, 15-minute limit per notebook), deploy.yml (documented placeholder pending spec §13 items 1 and 3 and the host choice).
  • Docs — repository README.md, site/README.md, pipelines/README.md (Phase 2 skeleton), this file.

Known gaps (Phase 0 exit criteria not yet met)

  • Answer keys derived from data, not yet confirmed by the author: L0.4 eyes-closed onset (75 s ± 2 s, from the LEMON segment’s marker; the algorithmic detector says 74 s) and the four L1.5 P3 amplitudes (from nb-1-5-filters on ds-brain-invaders subject 1, Pz, 300–500 ms).

  • The artifact bank lacks ecg, bridging and drowsiness items (not derivable from the Phase 0 data); 10 of its 67 items are labelled synthetic derivatives (electrode pop, flat channel).

  • Only headless screenshots and SSR/unit tests exercised the widgets; a hands-on browser pass is still due.

  • Labels on every drill item and scroller annotation are algorithmic; the author’s review to expert is pending (§4.5).

  • TODO(confirm) markers remain in the three P0 lessons and in generated dataset pages where the catalog is silent.

  • Colab links and deploy are blocked on spec §13 items 1 and 3.