From 79ddf22774aec200ea76ebf01d58c190a00eeac1 Mon Sep 17 00:00:00 2001
From: 611 <karmaone@163.com>
Date: Sun, 12 Jul 2026 14:57:23 -0400
Subject: [PATCH] Fix naming robustness and validator compliance across
 flat/deep datasets
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- filename_tokenizer: _pick supports whole-segment mode (omit position),
  default segment=-1, robust to letter/digit tokenization (S01, PD01)
- filename_tokenizer: _match handles **/ glob for root-level flat files
- planner: add evidence gate — demote session/run to none when constant
  or resolving to <2 distinct values across all files
- planner: subject-count guard no longer short-circuits on empty map
- executor: inject ses- into DICOM filenames when subdir has a session
  layer, keeping directory and filename consistent
- eeg_convert: bootstrap empty TSV cells to n/a; drop duplicate row append
---
 .autobidsify_session                   |   1 -
 .gitignore                             |   9 +-
 README.md                              |  14 +-
 autobidsify/bids_grammar.py            | 208 ++++++++++++++++++
 autobidsify/converters/eeg_convert.py  |  10 +-
 autobidsify/converters/executor.py     | 141 ++++++++++--
 autobidsify/converters/mri_convert.py  |  44 ++++
 autobidsify/converters/nirs_convert.py |   5 +-
 autobidsify/converters/planner.py      | 286 ++++++++++++++++++++++++-
 autobidsify/filename_tokenizer.py      | 231 ++++++++++++++++++++
 autobidsify/llm.py                     |  56 ++++-
 11 files changed, 977 insertions(+), 28 deletions(-)
 delete mode 100644 .autobidsify_session
 create mode 100644 autobidsify/bids_grammar.py

diff --git a/.autobidsify_session b/.autobidsify_session
deleted file mode 100644
index 0c22ef8..0000000
--- a/.autobidsify_session
+++ /dev/null
@@ -1 +0,0 @@
-/drives/jin1/users/roseliu/auto_bidsify/outputs_new/run3/run3-qwen3-n
\ No newline at end of file
diff --git a/.gitignore b/.gitignore
index b553682..195cb67 100644
--- a/.gitignore
+++ b/.gitignore
@@ -67,4 +67,11 @@ backups/
 *.bak
 
 # Misc
-bump_version.py
\ No newline at end of file
+bump_version.py
+
+# Tests
+repeatability/
+repeatability_config.py
+repeatability_run.out
+run_repeatability.py
+repeatability_full.out
\ No newline at end of file
diff --git a/README.md b/README.md
index 429be89..3f10b80 100644
--- a/README.md
+++ b/README.md
@@ -326,22 +326,22 @@ https://github.com/yiyiliu-rose/autobidsifyAPP/releases
 Two versions are provided:
 
 **AutoBIDSify ExecVal** — Execute and validate only. No AI or API key required.
-Runs the `execute` and `validate` stages locally using a pre-generated BIDS plan.
+Runs the `execute` and `validate` stages locally using a pre-generated BIDS plan. https://github.com//autobidsifyAPP.git
 
 | Platform              | Download                                                                                                                                                     |
 | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| Windows               | [AutoBIDSify-ExecVal-Windows.zip](https://github.com/yiyiliu-rose/autobidsifyAPP/releases/download/latest-execval/AutoBIDSify-ExecVal-Windows.zip)         |
-| macOS (Apple Silicon) | [AutoBIDSify-ExecVal-macOS-arm64.zip](https://github.com/yiyiliu-rose/autobidsifyAPP/releases/download/latest-execval/AutoBIDSify-ExecVal-macOS-arm64.zip) |
-| Linux                 | [AutoBIDSify-ExecVal-Linux.tar.gz](https://github.com/yiyiliu-rose/autobidsifyAPP/releases/download/latest-execval/AutoBIDSify-ExecVal-Linux.tar.gz)       |
+| Windows               | [AutoBIDSify-ExecVal-Windows.zip](https://github.com/NeuroJSON/autobidsifyAPP/releases/download/latest-execval/AutoBIDSify-ExecVal-Windows.zip)         |
+| macOS (Apple Silicon) | [AutoBIDSify-ExecVal-macOS-arm64.zip](https://github.com/NeuroJSON/autobidsifyAPP/releases/download/latest-execval/AutoBIDSify-ExecVal-macOS-arm64.zip) |
+| Linux                 | [AutoBIDSify-ExecVal-Linux.tar.gz](https://github.com/NeuroJSON/autobidsifyAPP/releases/download/latest-execval/AutoBIDSify-ExecVal-Linux.tar.gz)       |
 
 **AutoBIDSify Full** — Complete pipeline with AI. Requires an OpenAI API key, local Ollama model, or DashScope API key.
 Runs the full AutoBIDSify pipeline from ingestion to validation.
 
 | Platform              | Download                                                                                                                                                        |
 | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Windows               | [AutoBIDSify-Full-Windows.zip](https://github.com/yiyiliu-rose/autobidsifyAPP/releases/download/latest-full/AutoBIDSify-Full-Windows.zip)         |
-| macOS (Apple Silicon) | [AutoBIDSify-Full-macOS-arm64.zip](https://github.com/yiyiliu-rose/autobidsifyAPP/releases/download/latest-full/AutoBIDSify-Full-macOS-arm64.zip) |
-| Linux                 | [AutoBIDSify-Full-Linux.tar.gz](https://github.com/yiyiliu-rose/autobidsifyAPP/releases/download/latest-full/AutoBIDSify-Full-Linux.tar.gz)       |
+| Windows               | [AutoBIDSify-Full-Windows.zip](https://github.com/NeuroJSON/autobidsifyAPP/releases/download/latest-full/AutoBIDSify-Full-Windows.zip)         |
+| macOS (Apple Silicon) | [AutoBIDSify-Full-macOS-arm64.zip](https://github.com/NeuroJSON/autobidsifyAPP/releases/download/latest-full/AutoBIDSify-Full-macOS-arm64.zip) |
+| Linux                 | [AutoBIDSify-Full-Linux.tar.gz](https://github.com/NeuroJSON/autobidsifyAPP/releases/download/latest-full/AutoBIDSify-Full-Linux.tar.gz)       |
 
 Linux note: both desktop apps require a desktop environment with Tk and are built for GLIBC 2.35+.
 
diff --git a/autobidsify/bids_grammar.py b/autobidsify/bids_grammar.py
new file mode 100644
index 0000000..75f3563
--- /dev/null
+++ b/autobidsify/bids_grammar.py
@@ -0,0 +1,208 @@
+# bids_grammar.py
+# Single source of truth for BIDS filename grammar and required-metadata rules.
+#
+# Everything that decides "what a legal BIDS filename looks like" lives here, so
+# that name assembly (executor) and sidecar generation share ONE rule set instead
+# of each re-deriving order/legality with ad-hoc string surgery. Adding a modality
+# means adding rows to these tables, not editing assembly logic.
+#
+# Rules encoded here come directly from the BIDS spec and the MRS-BIDS extension
+# (Bouchard et al., Sci Data 2025, https://doi.org/10.1038/s41597-025-05543-2):
+#   - filenames are  sub-<label>[_ses-..]_<entities>_<suffix>.<ext>
+#   - all entities have ONE fixed order and each entity appears at most once
+#   - which entities are legal is decided by the datatype (anat has NO task;
+#     func/nirs/eeg REQUIRE task; mrs may carry nuc/voi/rec/echo/inv)
+#   - the suffix is constrained by the datatype (mrs -> svs|mrsi|mrsref|unloc)
+#   - the datatype also fixes which sidecar fields are REQUIRED
+
+import re
+from typing import Dict, List, Tuple, Optional
+
+# ---------------------------------------------------------------------------
+# 1) Canonical entity order.
+#    run MUST come after task and acq. This single total order is consistent
+#    with EVERY datatype row of the BIDS entity table:
+#      MRI  task acq ce rec dir run      (nuc/voi absent)
+#      dwi  acq dir run
+#      MRS  task acq nuc voi rec run echo inv   (ce/dir absent, MRS-BIDS Fig.1)
+#    No datatype uses both ce and nuc, so placing nuc/voi between ce and rec
+#    keeps both the MRI and MRS orders intact. Assembling in this order makes
+#    the CamCAN "run-3_task-rest" (run before task) bug structurally impossible.
+# ---------------------------------------------------------------------------
+CANONICAL_ORDER: List[str] = [
+    "sub", "ses", "task", "acq", "ce", "nuc", "voi", "rec", "dir",
+    "run", "echo", "inv",
+]
+
+# ---------------------------------------------------------------------------
+# 2) Which entities each datatype is ALLOWED to carry (sub/ses are structural
+#    and always allowed, so they are omitted here). Any entity a naming_entry
+#    supplies that is not in this set is DROPPED before assembly — this is what
+#    stops task- from leaking onto anat (T1w) files.
+# ---------------------------------------------------------------------------
+DATATYPE_ALLOWED_ENTITIES: Dict[str, set] = {
+    "anat": {"acq", "rec", "run"},                 # no task
+    "func": {"task", "acq", "rec", "run", "echo"}, # task required
+    "dwi":  {"acq", "dir", "run"},
+    "nirs": {"task", "acq", "run"},                # task required
+    "eeg":  {"task", "acq", "run"},                # task required
+    "mrs":  {"task", "acq", "nuc", "voi", "rec", "run", "echo", "inv"},
+}
+
+# ---------------------------------------------------------------------------
+# 3) Entities that are REQUIRED for a datatype. A missing required entity means
+#    files that differ only by that entity would collide, so the caller should
+#    block rather than emit a colliding name.
+# ---------------------------------------------------------------------------
+DATATYPE_REQUIRED_ENTITIES: Dict[str, set] = {
+    "func": {"task"},
+    "nirs": {"task"},
+    "eeg":  {"task"},
+}
+
+# ---------------------------------------------------------------------------
+# 4) Legal suffixes per datatype and the default when only the datatype is known.
+#    MRS-BIDS: SVS -> svs, MRSI -> mrsi, reference -> mrsref, no localization
+#    -> unloc.
+# ---------------------------------------------------------------------------
+DATATYPE_SUFFIXES: Dict[str, set] = {
+    "anat": {"T1w", "T2w", "T1rho", "T2star", "FLAIR", "FLASH", "PD",
+             "PDT2", "inplaneT1", "inplaneT2", "angio"},
+    "func": {"bold", "sbref"},
+    "dwi":  {"dwi"},
+    "nirs": {"nirs"},
+    "eeg":  {"eeg"},
+    "mrs":  {"svs", "mrsi", "mrsref", "unloc"},
+}
+DATATYPE_DEFAULT_SUFFIX: Dict[str, str] = {
+    "anat": "T1w", "func": "bold", "dwi": "dwi",
+    "nirs": "nirs", "eeg": "eeg", "mrs": "svs",
+}
+
+# ---------------------------------------------------------------------------
+# 5) Required JSON sidecar fields per datatype, plus entity-conditioned
+#    requirements. Values here are the KEY NAMES the sidecar must contain; the
+#    caller fills the actual values from the source file / --describe. MRS-BIDS
+#    mandates ResonantNucleus, SpectrometerFrequency, SpectralWidth, EchoTime.
+# ---------------------------------------------------------------------------
+DATATYPE_REQUIRED_SIDECAR: Dict[str, List[str]] = {
+    "func": ["TaskName", "RepetitionTime"],
+    "nirs": ["TaskName", "SamplingFrequency",
+             "NIRSChannelCount", "NIRSSourceOptodeCount",
+             "NIRSDetectorOptodeCount"],
+    "eeg":  ["TaskName", "SamplingFrequency", "EEGReference",
+             "PowerLineFrequency"],
+    "mrs":  ["ResonantNucleus", "SpectrometerFrequency",
+             "SpectralWidth", "EchoTime"],
+    "anat": [],
+    "dwi":  [],
+}
+# entity present in filename -> extra required sidecar keys (MRS-BIDS)
+ENTITY_CONDITIONED_SIDECAR: Dict[str, List[str]] = {
+    "nuc": ["ResonantNucleus"],
+    "voi": ["BodyPart", "BodyPartDetails"],
+}
+
+
+def sanitize_label(value: str) -> str:
+    """BIDS entity values must be purely alphanumeric — strip everything else."""
+    return re.sub(r"[^A-Za-z0-9]", "", str(value))
+
+
+def normalize_datatype(datatype: str) -> str:
+    """Fold aliases onto canonical datatype folder names."""
+    d = (datatype or "").lower()
+    if d in ("fnirs",):
+        return "nirs"
+    if d in ("mri",):          # 'mri' is a modality, not a datatype
+        return "anat"
+    return d
+
+
+def resolve_suffix(datatype: str, suffix: Optional[str]) -> str:
+    """
+    Return a legal suffix for the datatype. If the requested suffix is not
+    legal for this datatype, fall back to the datatype default so we never emit
+    an mrs file suffixed 'bold' or an anat file suffixed 'nirs'.
+    """
+    dt = normalize_datatype(datatype)
+    legal = DATATYPE_SUFFIXES.get(dt, set())
+    if suffix and suffix in legal:
+        return suffix
+    return DATATYPE_DEFAULT_SUFFIX.get(dt, suffix or "unknown")
+
+
+def assemble_bids_name(
+    subject: str,
+    entities: Dict[str, str],
+    datatype: str,
+    suffix: str,
+    ext: str,
+) -> Tuple[str, List[str], List[str]]:
+    """
+    Build a BIDS filename from a subject id, a bag of entities, a datatype and a
+    suffix, enforcing legality and canonical order.
+
+    Returns (filename, dropped_entities, missing_required_entities).
+
+      - entities not allowed for this datatype are DROPPED (e.g. task on anat)
+      - remaining entities are emitted in CANONICAL_ORDER (run always after task)
+      - required-but-absent entities are reported so the caller can block
+
+    `subject` and entity values are sanitized to alphanumeric. `ext` should
+    include the leading dot (e.g. '.nii.gz').
+    """
+    dt = normalize_datatype(datatype)
+    allowed = DATATYPE_ALLOWED_ENTITIES.get(dt, set())
+    required = DATATYPE_REQUIRED_ENTITIES.get(dt, set())
+
+    clean: Dict[str, str] = {}
+    dropped: List[str] = []
+    for key, val in (entities or {}).items():
+        if key in ("sub", "ses"):
+            continue  # handled structurally below
+        if val in (None, "", "none"):
+            continue
+        if key not in allowed:
+            dropped.append(key)
+            continue
+        clean[key] = sanitize_label(val)
+
+    missing = sorted(r for r in required if r not in clean)
+
+    parts = [f"sub-{sanitize_label(subject)}"]
+    ses = entities.get("ses") if entities else None
+    if ses:
+        parts.append(f"ses-{sanitize_label(ses)}")
+    for key in CANONICAL_ORDER:
+        if key in ("sub", "ses"):
+            continue
+        if key in clean:
+            parts.append(f"{key}-{clean[key]}")
+
+    suffix = resolve_suffix(dt, suffix)
+    filename = "_".join(parts) + "_" + suffix + ext
+    return filename, dropped, missing
+
+
+def bids_stem(filename: str) -> str:
+    """Strip the suffix+extension, keep the entity string. Used as a group key."""
+    name = filename
+    for e in (".nii.gz", ".snirf", ".nii", ".edf", ".vhdr", ".set", ".bdf",
+              ".json", ".gz"):
+        if name.endswith(e):
+            name = name[: -len(e)]
+            break
+    return name
+
+
+def required_sidecar_fields(datatype: str, entities: Dict[str, str]) -> List[str]:
+    """Full list of sidecar keys that must be present for this file."""
+    dt = normalize_datatype(datatype)
+    fields = list(DATATYPE_REQUIRED_SIDECAR.get(dt, []))
+    for ent, extra in ENTITY_CONDITIONED_SIDECAR.items():
+        if entities and entities.get(ent):
+            for k in extra:
+                if k not in fields:
+                    fields.append(k)
+    return fields
diff --git a/autobidsify/converters/eeg_convert.py b/autobidsify/converters/eeg_convert.py
index ac24413..383f3db 100644
--- a/autobidsify/converters/eeg_convert.py
+++ b/autobidsify/converters/eeg_convert.py
@@ -568,8 +568,12 @@ def _generate_eeg_channels_tsv(
             ch_type = "MISC"
 
         unit = channel_units[i] if i < len(channel_units) else "n/a"
+        if not str(unit).strip():
+            unit = "n/a"
         fs_val = str(sampling_rates[i]) if i < len(sampling_rates) else "n/a"
-        rows.append("\t".join([label, ch_type, unit, fs_val, "good"]))
+        fields = [label, ch_type, unit, fs_val, "good"]
+        fields = [f if str(f).strip() else "n/a" for f in fields]
+        rows.append("\t".join(fields))
 
     out_path.write_text("\n".join(rows) + "\n", encoding="utf-8")
     info(f"  ✓ {out_path.name} ({len(channel_labels)} channels)")
@@ -630,7 +634,9 @@ def _generate_eeg_events_tsv(
     header = ["onset", "duration", "trial_type"]
     lines = ["\t".join(header)]
     for ev in events:
-        lines.append("\t".join(str(ev[h]) for h in header))
+        cells = [str(ev.get(h, "")) for h in header]
+        cells = [c if c.strip() else "n/a" for c in cells]
+        lines.append("\t".join(cells))
     out_path.write_text("\n".join(lines) + "\n", encoding="utf-8")
     info(f"  ✓ {out_path.name} ({len(events)} event(s))")
 
diff --git a/autobidsify/converters/executor.py b/autobidsify/converters/executor.py
index b6702f7..2429d41 100644
--- a/autobidsify/converters/executor.py
+++ b/autobidsify/converters/executor.py
@@ -25,6 +25,7 @@
     scrub_text_file,
     is_text_scrubbable,
 )
+from autobidsify.converters.mri_convert import generate_mri_bids_sidecar
 
 
 def _sanitize_bids_label(label: str) -> str:
@@ -494,6 +495,65 @@ def categorize_scan_type(suffix: str) -> str:
     return "unknown"
 
 
+def _analysis_from_naming_entry(filepath: str, e: Dict[str, str],
+                                modality: str) -> Dict[str, Any]:
+    """Build the analysis dict from naming_structure entities via bids_grammar.
+
+    naming_structure is authoritative: Python already resolved subject/ses/task/
+    acq/run for this file. Here we only choose the bare suffix + extension for the
+    modality, then hand the entity bag to assemble_bids_name(), which enforces
+    canonical order and drops entities illegal for the datatype (so a task value
+    can never land on an anat T1w file, and run always follows task).
+    """
+    from autobidsify.bids_grammar import assemble_bids_name, sanitize_label
+
+    if modality == "nirs":
+        datatype, suffix, ext = "nirs", "nirs", ".snirf"
+    elif modality == "eeg":
+        oe = "." + filepath.rsplit(".", 1)[-1] if "." in filepath else ""
+        ext = oe if oe in (".edf", ".vhdr", ".set", ".bdf") else ".edf"
+        datatype, suffix = "eeg", "eeg"
+    elif modality == "mrs":
+        # MRS: suffix comes from the naming entry (svs/mrsi/mrsref/unloc),
+        # default svs; data lives in mrs/ as NIfTI-MRS.
+        datatype, suffix, ext = "mrs", (e.get("_suffix") or "svs"), ".nii.gz"
+    else:
+        # MRI: reuse scan-type inference but keep ONLY the bare suffix token
+        # (T1w/bold/dwi). Any task/acq/run the heuristic packed into the suffix
+        # is discarded — entities come from the naming entry, which is authoritative.
+        si = infer_scan_type_from_filepath(filepath, [], modality="mri")
+        suffix   = si["suffix"].split("_")[-1]      # strip packed entities
+        datatype = si["subdirectory"]               # anat / func / dwi
+        ext      = ".nii.gz"
+
+    entities = {
+        "ses":  e.get("ses"),
+        "task": e.get("task"),
+        "acq":  e.get("acq"),
+        "run":  e.get("run"),
+        "nuc":  e.get("nuc"),
+        "voi":  e.get("voi"),
+    }
+
+    bids_filename, dropped, missing = assemble_bids_name(
+        subject=e["subject"], entities=entities,
+        datatype=datatype, suffix=suffix, ext=ext,
+    )
+    subdir = (f"ses-{sanitize_label(e['ses'])}/{datatype}"
+              if e.get("ses") else datatype)
+
+    return {
+        "subject_id":        e["subject"],
+        "scan_type_suffix":  suffix,
+        "bids_filename":     bids_filename,
+        "subdirectory":      subdir,
+        "scan_category":     datatype,
+        "original_filepath": filepath,
+        "modality":          modality,
+        "_missing_entities": missing,   # func/nirs/eeg with no task shows up here
+    }
+
+
 # ============================================================================
 # Universal filepath analyzer
 # ============================================================================
@@ -503,6 +563,7 @@ def analyze_filepath_universal(
     assignment_rules: List[Dict],
     filename_rules: List[Dict],
     modality: str = "mri",
+    naming_entry: Optional[Dict[str, str]] = None,
 ) -> Dict[str, Any]:
     """
     Determine the BIDS subject ID and output filename for a source file.
@@ -514,6 +575,9 @@ def analyze_filepath_universal(
     4. Standard BIDS sub-XX pattern already in the path.
     5. Fallback: 'unknown'.
     """
+    if naming_entry and naming_entry.get("subject"):
+        return _analysis_from_naming_entry(filepath, naming_entry, modality)
+
     filename   = filepath.split("/")[-1]
     path_parts = filepath.split("/")
     subject_id: Optional[str] = None
@@ -625,6 +689,8 @@ def execute_bids_plan(
 
     logs:     List[Dict] = []
     successes = failures = 0
+    written_targets: Dict[str, str] = {}      # dst path -> source that wrote it
+    collisions: List[Dict[str, str]] = []     # never overwrite silently
 
     # ── Step 1: copy trio files ───────────────────────────────────────
     info("\n[1/5] Organizing trio files...")
@@ -643,6 +709,19 @@ def execute_bids_plan(
     path_str_to_path = {s: p for s, p in zip(all_files_str, all_files_paths)}
     info(f"Total files: {len(all_files_str)}")
 
+    naming_structure = plan.get("naming_structure", [])
+    id_strategy = (plan.get("metadata") or {}).get("id_strategy", "auto")
+    naming_per_file = {}
+    if naming_structure:
+        from autobidsify.filename_tokenizer import expand_naming_structure
+        _naming_exts = ('.snirf', '.nirs', '.mat', '.dcm', '.nii', '.nii.gz',
+                        '.jnii', '.bnii', '.edf', '.vhdr', '.set', '.bdf')
+        _data_only = [f for f in all_files_str if f.lower().endswith(_naming_exts)]
+        _nsub = (plan.get("subjects") or {}).get("count")
+        naming_per_file, _ = expand_naming_structure(
+            _data_only, naming_structure, id_strategy, nsubjects=_nsub)
+        info(f"  naming_structure covered {len(naming_per_file)} file(s)")
+
     assignment_rules: List[Dict] = plan.get("assignment_rules", [])
     mappings:         List[Dict] = plan.get("mappings", [])
     info(f"  Assignment rules: {len(assignment_rules)} subjects")
@@ -709,8 +788,9 @@ def execute_bids_plan(
                     fp = path_str_to_path.get(fp_str)
                     if not fp:
                         continue
-                    analysis = analyze_filepath_universal(fp_str, assignment_rules,
-                                                             filename_rules, modality="nirs")
+                    analysis = analyze_filepath_universal(
+                        fp_str, assignment_rules, filename_rules,
+                        modality="nirs", naming_entry=naming_per_file.get(fp_str))
                     dst = (bids_root
                            / f"sub-{analysis['subject_id']}"
                            / analysis.get("subdirectory", "nirs")
@@ -818,7 +898,8 @@ def execute_bids_plan(
         # ── MRI / format-ready: analyze → group → convert / copy ──────
         file_analyses = [
             analyze_filepath_universal(f, assignment_rules, filename_rules,
-                                       modality=modality)
+                                       modality=modality,
+                                       naming_entry=naming_per_file.get(f))
             for f in matched_files
         ]
 
@@ -836,12 +917,13 @@ def execute_bids_plan(
                 fname_base = _normalize_filename(fp_str)
                 group_key  = f"{subj}_{scan_suffix}_{fname_base}"
             else:
-                # For non-DICOM files (fNIRS SNIRF, NIfTI), include the
-                # filename base in the group key so that multiple files
-                # with the same subject+suffix but different names
-                # (e.g. different tasks) are kept as separate scan groups.
-                fname_base_nir = _normalize_filename(fp_str)
-                group_key = f"{subj}_{scan_suffix}_{fname_base_nir}"
+                # Key on the FULL assembled BIDS name (all entities included) so
+                # files that differ only by run/ses/acq/task stay in SEPARATE
+                # groups. Same run+suffix but different source format (BRIK vs
+                # NIfTI) still share one key and get deduped by _select_preferred_file.
+                from autobidsify.bids_grammar import bids_stem
+                group_key = (f"{subj}/{analysis['subdirectory']}/"
+                             f"{bids_stem(analysis['bids_filename'])}")
 
             if group_key not in file_groups:
                 if is_dicom:
@@ -871,6 +953,16 @@ def execute_bids_plan(
                         bids_fname = f"sub-{subj}_acq-{acq_label}_{scan_suffix}.nii.gz"
 
                     subdir = analysis["subdirectory"]
+                    # Keep ses consistent between directory and filename. The
+                    # hand-built DICOM name above omits ses-, but subdir may
+                    # carry ses-N/ (from the naming entry). BIDS requires both
+                    # sides to match, so inject ses- into the filename whenever
+                    # the subdir has a session layer.
+                    _m = re.match(r"ses-([A-Za-z0-9]+)/", subdir)
+                    if _m and "_ses-" not in bids_fname:
+                        _ses = _m.group(1)
+                        bids_fname = bids_fname.replace(
+                            f"sub-{subj}_", f"sub-{subj}_ses-{_ses}_", 1)
                 else:
                     bids_fname = analysis["bids_filename"]
                     subdir     = analysis["subdirectory"]
@@ -928,6 +1020,17 @@ def execute_bids_plan(
                                 else fp.suffix.lower()
 
                 dst = bids_root / f"sub-{subj}" / subdirectory / bids_filename
+
+                dst = bids_root / f"sub-{subj}" / subdirectory / bids_filename
+                _key = str(dst)
+                if _key in written_targets:
+                    warn(f"      ✗ COLLISION: {bids_filename} already written from "
+                         f"'{written_targets[_key]}', skipping '{fp_str}' (data would be lost)")
+                    collisions.append({"target": _key,
+                                       "kept": written_targets[_key],
+                                       "dropped": fp_str})
+                    failures += 1
+                    continue
                 ensure_dir(dst.parent)
 
                 done = False
@@ -1041,6 +1144,9 @@ def execute_bids_plan(
                     copy_file(fp, dst)
                     successes += 1; done = True
                     processed_sources.add(fp_str)
+                    # BIDS-required sidecar for functional MRI: TaskName + RepetitionTime.
+                    from autobidsify.converters.mri_convert import generate_mri_bids_sidecar
+                    generate_mri_bids_sidecar(dst, bids_filename, subdirectory)
                     if deface and subdirectory == "anat" and dst.exists():
                         deface_nifti(dst)
 
@@ -1049,6 +1155,7 @@ def execute_bids_plan(
                     failures += 1
 
                 if done:
+                    written_targets[_key] = fp_str
                     logs.append({
                         "source":      fp_str,
                         "destination": f"sub-{subj}/{subdirectory}/{bids_filename}",
@@ -1120,6 +1227,13 @@ def execute_bids_plan(
     # ── Step 4: write logs and manifest ───────────────────────────────
     info("\n[4/5] Finalizing...")
     write_json(Path(output_dir) / "_staging" / "conversion_log.json", logs)
+    if naming_per_file:
+        write_json(Path(output_dir) / "_staging" / "naming_log.json", {
+            "generated_by": "autobidsify execute stage",
+            "files": naming_per_file,
+        })
+        info(f"  ✓ naming_log.json: {len(naming_per_file)} file(s)")
+    
     manifest_files = sorted(
         str(p.relative_to(bids_root)).replace("\\", "/")
         for p in bids_root.rglob("*") if p.is_file()
@@ -1165,9 +1279,10 @@ def execute_bids_plan(
         warn("⚠ WARNING: No subject directories created!")
 
     return {
-        "total_mappings":        len(mappings),
+        "total_mappings":         len(mappings),
         "successful_conversions": successes,
-        "failed_conversions":    failures,
-        "bids_root":             str(bids_root),
-        "subject_count":         len(subject_dirs),
+        "failed_conversions":     failures,
+        "collisions":             collisions,          # NEW
+        "bids_root":              str(bids_root),
+        "subject_count":          len(subject_dirs),
     }
\ No newline at end of file
diff --git a/autobidsify/converters/mri_convert.py b/autobidsify/converters/mri_convert.py
index fccbeaf..25f9115 100644
--- a/autobidsify/converters/mri_convert.py
+++ b/autobidsify/converters/mri_convert.py
@@ -322,3 +322,47 @@ def validate_nifti(nifti_path: Path) -> bool:
     except Exception as e:
         warn(f"NIfTI validation failed for {nifti_path}: {e}")
         return False
+    
+
+def generate_mri_bids_sidecar(nifti_path: Path, bids_filename: str,
+                              subdirectory: str) -> None:
+    """
+    Write the BIDS-required JSON sidecar for an MRI file when its datatype needs one.
+
+    func (bold): TaskName and RepetitionTime are REQUIRED by the validator.
+      - TaskName comes from the task- entity in the filename.
+      - RepetitionTime is read from the NIfTI header's 4th voxel dimension (TR
+        in seconds). If the header has no TR, we warn honestly rather than
+        fabricate a value.
+    anat / dwi: no validator-required field, so no sidecar is forced.
+    """
+    import re
+    from autobidsify.bids_grammar import bids_stem, required_sidecar_fields
+    stem     = bids_stem(bids_filename)
+    suffix   = stem.split("_")[-1]
+    datatype = subdirectory.split("/")[-1]        # strip any ses-XX/ prefix
+
+    required = required_sidecar_fields(datatype, {})
+    if not required:                              # anat / dwi
+        return
+
+    sidecar: Dict[str, Any] = {}
+    m = re.search(r"task-([A-Za-z0-9]+)", bids_filename)
+    if "TaskName" in required:
+        sidecar["TaskName"] = m.group(1) if m else "rest"
+
+    if "RepetitionTime" in required:
+        try:
+            img   = nib.load(str(nifti_path))
+            zooms = img.header.get_zooms()
+            if len(zooms) >= 4 and float(zooms[3]) > 0:
+                sidecar["RepetitionTime"] = round(float(zooms[3]), 6)
+        except Exception:
+            pass
+        if "RepetitionTime" not in sidecar:
+            warn(f"  ⚠ {nifti_path.name}: no RepetitionTime in NIfTI header; "
+                 f"validator will flag it. Add TR to the source data or --describe.")
+
+    json_path = nifti_path.parent / (stem + ".json")
+    write_json(json_path, sidecar)
+    info(f"  ✓ MRI sidecar: {json_path.name} ({', '.join(sidecar.keys())})")
diff --git a/autobidsify/converters/nirs_convert.py b/autobidsify/converters/nirs_convert.py
index e32cef3..898bb77 100644
--- a/autobidsify/converters/nirs_convert.py
+++ b/autobidsify/converters/nirs_convert.py
@@ -1791,8 +1791,9 @@ def _generate_coordsystem_json(
         return
 
     write_json(out_path, {
-        "NIRSCoordinateSystem":      "unknown",
-        "NIRSCoordinateSystemUnits": "mm",
+        "NIRSCoordinateSystem":            "Other",
+        "NIRSCoordinateSystemDescription": "Coordinate system not specified in the source data.",
+        "NIRSCoordinateUnits":             "mm",
     })
     info(f"  ✓ {out_path.name}")
 
diff --git a/autobidsify/converters/planner.py b/autobidsify/converters/planner.py
index 7269725..1827c79 100644
--- a/autobidsify/converters/planner.py
+++ b/autobidsify/converters/planner.py
@@ -12,6 +12,10 @@
 from autobidsify.llm import llm_nirs_draft, llm_nirs_normalize, llm_bids_plan
 from autobidsify.llm import llm_map_mat_to_snirf, llm_map_eeg_events, llm_analyze_eeg_aux
 from autobidsify.converters.nirs_convert import inspect_mat_structure, _structure_fingerprint
+from autobidsify.converters.nirs_convert import inspect_mat_structure, _structure_fingerprint
+from autobidsify.filename_tokenizer import (
+    FilenameTokenizer, FilenamePatternAnalyzer, expand_naming_structure,
+)
 from autobidsify.anonymize import scrub_text, scrub_participants_tsv
 
 HEADERS_DRAFT      = "nirs_headers_draft.json"
@@ -241,6 +245,27 @@ def _sort_key(sid: str):
     info(f"  ✓ participants.tsv: {len(ordered)} subjects, columns: {columns}")
 
 
+def _write_participants_from_subject_map(subject_map: Dict[str, str],
+                                         out_dir: Path) -> None:
+    """
+    Write participants.tsv from the naming_structure expansion.
+    subject_map: {subject_id: original_id}. Authoritative subject source.
+    """
+    parts_path = out_dir / "participants.tsv"
+    if parts_path.exists():
+        parts_path.unlink()
+
+    def _sort_key(sid: str):
+        try:    return (0, int(sid))
+        except: return (1, sid)
+
+    lines = ["participant_id\toriginal_id\n"]
+    for sid in sorted(subject_map.keys(), key=_sort_key):
+        lines.append(f"sub-{sid}\t{subject_map[sid]}\n")
+    parts_path.write_text("".join(lines))
+    info(f"  ✓ participants.tsv: {len(subject_map)} subjects (from naming_structure)")
+
+
 def _merge_participants_from_llm_metadata(
     plan_yaml: Dict[str, Any],
     out_dir: Path,
@@ -606,6 +631,171 @@ def _build_eeg_aux_mapping(
     return f"_staging/{EEG_AUX_MAPPING_FILE}"
 
 
+NAMING_STRUCTURE_KEY = "naming_structure"
+
+def _layout_signature(relpath: str) -> tuple:
+    parts = relpath.split('/')
+    fname_toks = FilenameTokenizer.tokenize(parts[-1])
+    shape = tuple('d' if t.isdigit() else 'a' for t in fname_toks)
+    return (len(parts), len(fname_toks), shape)
+
+def _build_naming_structure(model, data_files, describe, id_strategy):
+    """One LLM call per layout signature. Returns list of naming_structure entries."""
+    from autobidsify.llm import llm_label_naming_structure
+    from autobidsify.filename_tokenizer import FilenamePatternAnalyzer
+    import yaml as _yaml
+    groups = {}
+    for f in data_files:
+        groups.setdefault(_layout_signature(f), []).append(f)
+    entries = []
+    for sig, files in groups.items():
+        # build per-segment position distributions for this group
+        max_depth = min(sig[0], 4)
+        seg_stats = {}
+        for seg in range(-1, -max_depth - 1, -1):
+            names = [ff.split('/')[seg] for ff in files if abs(seg) <= len(ff.split('/'))]
+            seg_stats[seg] = FilenamePatternAnalyzer(names).analyze_token_statistics().get("token_positions", {})
+        payload = json.dumps({
+            "segment_distributions": {str(k): v for k, v in seg_stats.items()},
+            "samples": [{"path": ff, "tokens_seg_-1": FilenameTokenizer.tokenize(ff.split('/')[-1])}
+                        for ff in files[:8]],
+            "describe": describe,
+            "id_strategy": id_strategy,
+        }, indent=2)
+        try:
+            resp = llm_label_naming_structure(model, payload)
+            txt = resp.strip()
+            if txt.startswith("```"): txt = "\n".join(txt.split("\n")[1:])
+            if txt.endswith("```"): txt = txt[:-3]
+            parsed = _yaml.safe_load(txt.strip())
+            # LLM may return a single dict or a list; normalise to a list
+            candidates = parsed if isinstance(parsed, list) else [parsed]
+            # Python OWNS matching entirely: applies_to is always derived from the
+            # actual extensions present in THIS group's files. The LLM's own
+            # applies_to is ignored, so it can never inject globs (e.g. *.dcm,
+            # *.snirf) for file types this dataset does not contain.
+            exts = sorted({('.' + ff.rsplit('.', 1)[-1]).lower()
+                           for ff in files if '.' in ff})
+            if len(exts) == 1:
+                group_match = '**/*' + exts[0]
+            elif len(exts) > 1:
+                group_match = '**/*'      # mixed group: match any, roles still apply
+            else:
+                group_match = '**/*'
+            for cand in candidates:
+                if not isinstance(cand, dict):
+                    continue
+                roles = cand.get("roles")
+                if not isinstance(roles, dict) or not roles:
+                    continue
+                # take only the LLM's role labels; discard its applies_to
+                ap = {"match": group_match}
+                entries.append({"applies_to": ap, "roles": roles,
+                                "_fname_shape": [sig[1], sig[2]]})
+        except Exception as e:
+            warn(f"  naming_structure: group {sig} failed: {e}")
+    return entries
+
+
+def _reconcile_naming_structure(entries):
+    """
+    LLM may label structurally-identical groups inconsistently (e.g. it assigns
+    task to one modality but leaves another as mode:none even though both
+    filenames share the same token layout). Deterministically borrow a missing
+    role from a sibling entry that has the same filename token shape. No LLM.
+    Returns (entries, notes).
+    """
+    from collections import defaultdict
+
+    def _defined(spec):
+        return (isinstance(spec, dict)
+                and spec.get("mode") in ("from_path", "lookup", "constant"))
+
+    buckets = defaultdict(list)
+    for i, e in enumerate(entries):
+        buckets[tuple(map(str, e.get("_fname_shape") or []))].append(i)
+
+    notes = []
+    ROLE_NAMES = ("subject", "session", "run", "task", "acq")
+    for _key, idxs in buckets.items():
+        if len(idxs) < 2:
+            continue
+        for role in ROLE_NAMES:
+            donor = None
+            for i in idxs:
+                if _defined((entries[i].get("roles") or {}).get(role)):
+                    donor = entries[i]["roles"][role]
+                    break
+            if donor is None:
+                continue
+            for i in idxs:
+                roles = entries[i].setdefault("roles", {})
+                if not _defined(roles.get(role)):
+                    roles[role] = donor
+                    notes.append({"entry_index": i, "role": role,
+                                  "action": "borrowed_from_same_shape_sibling"})
+
+    for e in entries:
+        e.pop("_fname_shape", None)
+    return entries, notes
+
+
+def _apply_evidence_gate(naming_structure, data_files):
+    """Evidence gate for session/run. An entity that never distinguishes any
+    file is spurious (weak models invent constant or single-valued session/run
+    even when the data has neither). For each entry's 'session' and 'run' role:
+      - mode 'constant'                       -> demote to none (zero contrast)
+      - mode 'from_path' resolving to <2 distinct values across ALL files
+                                              -> demote to none (no contrast)
+      - mode 'from_path' with >=2 distinct    -> keep (real, e.g. ses1..ses6)
+    Uses the same _pick the executor uses, so gate and execution never diverge.
+    Returns a list of demotion records for provenance.
+    """
+    from autobidsify.filename_tokenizer import _pick
+
+    demotions = []
+    for entry in naming_structure or []:
+        roles = entry.get("roles", {})
+        if not isinstance(roles, dict):
+            continue
+        applies = (entry.get("applies_to") or {})
+        for role_name in ("session", "run"):
+            spec = roles.get(role_name)
+            if not isinstance(spec, dict):
+                continue
+            mode = spec.get("mode", "none")
+            if mode == "none":
+                continue
+
+            if mode == "constant":
+                roles[role_name] = {"mode": "none"}
+                demotions.append({
+                    "role": role_name, "reason": "constant (zero contrast)",
+                    "applies_to": applies,
+                    "old": spec.get("value"),
+                })
+                continue
+
+            if mode == "from_path":
+                sources = spec.get("sources", [])
+                join = spec.get("join", "")
+                seen = set()
+                for f in data_files:
+                    v = _pick(f, sources, join)
+                    if v not in (None, ""):
+                        seen.add(v)
+                if len(seen) < 2:
+                    roles[role_name] = {"mode": "none"}
+                    demotions.append({
+                        "role": role_name,
+                        "reason": f"from_path resolved to {len(seen)} distinct "
+                                  f"value(s) across {len(data_files)} files",
+                        "applies_to": applies,
+                        "distinct_values": sorted(seen),
+                    })
+    return demotions
+
+
 # ============================================================================
 # Main entry point
 # ============================================================================
@@ -730,10 +920,101 @@ def build_bids_plan(model: str, planning_inputs: Dict[str, Any],
         warn(f"  ⚠ LLM subject count ({llm_count}) ≠ user-provided count "
              f"({user_n_subjects}). Trusting LLM assignment_rules; updating count only.")
         plan_yaml["subjects"]["count"] = user_n_subjects
+    
+    # ── Step 4.5: naming_structure (authoritative for subject + entities) ──
+    info("\nStep 4.5: Building naming_structure...")
+    naming_structure = _build_naming_structure(model, data_files, describe, id_strategy)
+    # Self-check: LLM may label structurally-identical groups inconsistently.
+    # Deterministically borrow a missing role from a same-shape sibling group.
+    naming_structure, recon_notes = _reconcile_naming_structure(naming_structure)
+    if recon_notes:
+        plan_yaml["naming_structure_reconciliation"] = recon_notes
+        info(f"  reconciled {len(recon_notes)} role(s) across same-shape groups")
+
+    # Evidence gate: strip session/run roles that never distinguish any file.
+    _gate_demotions = _apply_evidence_gate(naming_structure, data_files)
+    if _gate_demotions:
+        plan_yaml["evidence_gate_demotions"] = _gate_demotions
+        for _d in _gate_demotions:
+            info(f"  ✓ demoted {_d['role']} to none — {_d['reason']}")
+
+    plan_yaml[NAMING_STRUCTURE_KEY] = naming_structure
+
+    # naming_structure is now the SINGLE authority for subject + entity
+    # resolution. Drop the legacy assignment_rules / filename_rules the LLM
+    # full-plan step may have emitted, so the executor cannot run two competing
+    # naming mechanisms and produce inconsistent, colliding output.
+    if naming_structure:
+        if plan_yaml.pop("assignment_rules", None) is not None:
+            info("  ✓ dropped legacy assignment_rules (naming_structure is authoritative)")
+        for _m in plan_yaml.get("mappings", []):
+            _m.pop("filename_rules", None)
+
+    from autobidsify.filename_tokenizer import expand_naming_structure
+    naming_per_file, naming_subject_map = expand_naming_structure(
+        data_files, naming_structure, id_strategy, nsubjects=user_n_subjects)
+    info(f"  naming_structure covered {len(naming_per_file)} file(s), "
+         f"{len(naming_subject_map)} subject(s)")
+
+    # ── Self-check (user --nsubjects is the authoritative oracle) ──────
+    plan_questions: List[Dict[str, Any]] = []
+
+    # Check 1: subject count. User-provided --nsubjects is assumed correct and
+    # has highest priority; a mismatch means naming_structure mis-resolved
+    # subjects. Block rather than silently emit a wrong dataset.
+    if user_n_subjects and len(naming_subject_map) != user_n_subjects:
+        got = len(naming_subject_map)
+        warn(f"  ⚠ naming_structure produced {got} subjects, "
+             f"but --nsubjects={user_n_subjects}")
+        plan_questions.append({
+            "severity": "block",
+            "message": (
+                f"naming_structure resolved {got} subject(s) but you specified "
+                f"--nsubjects {user_n_subjects}. The subject field was likely taken "
+                f"from the wrong part of the filename or path. Please clarify in "
+                f"--describe which part of the name identifies the subject "
+                f"(and, if applicable, which parts distinguish sites or sessions), "
+                f"then re-run."
+            ),
+        })
+
+    # Check 2: BIDS required-entity — nirs/eeg REQUIRE a task entity.
+    # A missing task means files differing only by task would collide.
+    _missing_task = [
+        rel for rel, e in naming_per_file.items()
+        if (rel.lower().endswith(('.snirf', '.nirs', '.mat',
+                                  '.edf', '.vhdr', '.set', '.bdf'))
+            and not e.get("task"))
+    ]
+    if _missing_task:
+        warn(f"  ⚠ {len(_missing_task)} nirs/eeg file(s) have no 'task' entity")
+        plan_questions.append({
+            "severity": "block",
+            "message": (
+                f"{len(_missing_task)} nirs/eeg file(s) could not be assigned a "
+                f"required 'task' entity (e.g. {_missing_task[0]}). Files that share "
+                f"subject/session/run but differ only by task would overwrite each "
+                f"other. Please explain in --describe how the task is encoded in the "
+                f"filename or metadata, then re-run."
+            ),
+        })
 
     # ── Step 5: Write participants.tsv ────────────────────────────────
     info("\nStep 5: Generating participants.tsv from LLM plan...")
-    _write_participants_from_plan(plan_yaml, out_dir, user_n_subjects)
+    if naming_subject_map:
+        # authoritative subjects from naming_structure
+        labels = sorted(naming_subject_map.keys(),
+                        key=lambda s: (len(s), s))
+        plan_yaml["subjects"] = {"count": len(labels), "labels": labels,
+                                 "id_strategy": id_strategy, "source": "naming_structure"}
+        # Replace entirely so stale LLM subject keys can't leak into the TSV
+        plan_yaml["participant_metadata"] = {
+            sid: {"original_id": raw} for sid, raw in naming_subject_map.items()
+        }
+        _write_participants_from_subject_map(naming_subject_map, out_dir)
+    else:
+        _write_participants_from_plan(plan_yaml, out_dir, user_n_subjects)
+    
     if anonymize:
         parts_path = out_dir / "participants.tsv"
         if parts_path.exists():
@@ -809,6 +1090,9 @@ def build_bids_plan(model: str, planning_inputs: Dict[str, Any],
 
     final_count = plan_yaml.get("subjects", {}).get("count", llm_count)
     info(f"\n=== Complete: {final_count} subjects ===")
+    if plan_questions:
+        warn("  ⚠ Plan has blocking questions — execute stage will be skipped")
+        return {"status": "blocked", "warnings": [], "questions": plan_questions}
     return {"status": "ok", "warnings": [], "questions": []}
 
 
diff --git a/autobidsify/filename_tokenizer.py b/autobidsify/filename_tokenizer.py
index 44ea01a..7ea8f0f 100644
--- a/autobidsify/filename_tokenizer.py
+++ b/autobidsify/filename_tokenizer.py
@@ -483,6 +483,237 @@ def create_blocking_question(reason: str, options: List[str]) -> Dict[str, Any]:
         }
 
 
+def _san_label(v: str) -> str:
+    # BIDS label: alphanumeric only
+    return re.sub(r'[^A-Za-z0-9]', '', str(v))
+
+def _san_index(v: str) -> str:
+    # BIDS run index: digits only, no leading zero loss handled as int
+    d = re.sub(r'[^0-9]', '', str(v))
+    return str(int(d)) if d else ''
+
+def _segment_tokens(relpath: str, segment: int) -> List[str]:
+    # split path, pick segment by negative index, strip ext on filename seg, tokenize
+    parts = relpath.split('/')
+    if abs(segment) > len(parts):
+        return []
+    seg = parts[segment]
+    return FilenameTokenizer.tokenize(seg)
+
+def _pick(relpath: str, sources: List[Dict], join: str = '') -> Optional[str]:
+    parts = relpath.split('/')
+    vals = []
+    for s in sources:
+        if not isinstance(s, dict):
+            continue
+        # segment defaults to -1 (filename) when the LLM omits it
+        seg = int(s.get('segment', -1))
+        if abs(seg) > len(parts):
+            return None
+        raw = parts[seg]
+        # strip extension only on the filename segment
+        if seg == -1:
+            low = raw.lower()
+            for e in ('.nii.gz', '.snirf', '.nirs', '.jnii', '.bnii',
+                      '.edf', '.vhdr', '.set', '.bdf', '.mat', '.dcm'):
+                if low.endswith(e):
+                    raw = raw[: -len(e)]
+                    break
+            else:
+                if '.' in raw:
+                    raw = raw.rsplit('.', 1)[0]
+        # WHOLE-SEGMENT mode: no 'position' key (or whole:true) → take the
+        # entire segment string, robust to letter/digit tokenization.
+        if s.get('whole') or 'position' not in s:
+            vals.append(raw)
+            continue
+        # POSITION mode: index into tokenized segment (back-compat)
+        toks = FilenameTokenizer.tokenize(raw)
+        pos = int(s['position'])
+        if pos < 0 or pos >= len(toks):
+            return None
+        vals.append(toks[pos])
+    return join.join(vals) if vals else None
+
+def _resolve_roles_partial(relpath: str, roles: Dict[str, Any]) -> Dict[str, str]:
+    """Resolve whatever roles CAN be resolved for one file, with NO subject gate.
+    Unlike resolve_file_entities, a failed subject does not discard the roles it
+    did resolve — this lets expand_naming_structure merge roles the LLM split
+    across multiple entries that share the same applies_to glob (one entry
+    carries acq, another carries task/run)."""
+    out: Dict[str, str] = {}
+    if not isinstance(roles, dict):
+        return out
+    for ent, spec in roles.items():
+        if not isinstance(spec, dict):
+            continue
+        mode = spec.get('mode', 'none')
+        if mode == 'none':
+            continue
+        if mode == 'constant':
+            val = spec.get('value')
+        elif mode == 'from_path':
+            val = _pick(relpath, spec.get('sources', []), spec.get('join', ''))
+        elif mode == 'lookup':
+            ks_list = spec.get('key_source')
+            if isinstance(ks_list, dict):
+                ks_list = [ks_list]
+            if not ks_list:
+                ks_list = spec.get('sources', [])
+            key = _pick(relpath, ks_list) if ks_list else None
+            val = (spec.get('table') or {}).get(key) if key is not None else None
+        else:
+            val = None
+        if val in (None, ''):
+            continue
+        out['ses' if ent == 'session' else ent] = val
+    return out
+
+def resolve_file_entities(relpath: str, roles: Dict[str, Any]) -> Optional[Dict[str, str]]:
+    """Apply one role-set to one file. Returns raw entities or None if subject unresolved."""
+    if not isinstance(roles, dict):
+        return None
+    if not isinstance(roles, dict):
+        return None
+    out = {}
+    for ent, spec in roles.items():
+        if not isinstance(spec, dict):
+            continue
+        mode = spec.get('mode', 'none')
+        if mode == 'none':
+            continue
+        if mode == 'constant':
+            val = spec.get('value')
+        elif mode == 'from_path':
+            val = _pick(relpath, spec.get('sources', []), spec.get('join', ''))
+        elif mode == 'lookup':
+            # tolerate LLM using 'sources' instead of 'key_source'
+            ks_list = spec.get('key_source')
+            if isinstance(ks_list, dict):
+                ks_list = [ks_list]
+            if not ks_list:
+                ks_list = spec.get('sources', [])
+            key = _pick(relpath, ks_list) if ks_list else None
+            val = (spec.get('table') or {}).get(key) if key is not None else None
+        else:
+            val = None
+        if val is None:
+            if ent == 'subject':
+                return None      # subject must resolve, else fall back
+            continue
+        # normalise role name 'session' to the BIDS entity key 'ses'
+        out['ses' if ent == 'session' else ent] = val
+    return out if out.get('subject') is not None else None
+
+def expand_naming_structure(files: List[str], naming_structure: List[Dict],
+                            id_strategy: str = 'auto',
+                            nsubjects: Optional[int] = None):
+    """
+    Deterministically expand naming_structure over all data files.
+    Returns (per_file, subject_map):
+      per_file[relpath] = {subject, subject_raw, ses, run, task, acq}
+      subject_map[subject_id] = original_id
+    """
+    def _match(relpath, applies_to):
+        import fnmatch
+        if not isinstance(applies_to, dict):
+            return False
+        pat = applies_to.get('match')
+        if not pat:
+            return True
+        # A '**/' prefix means "any depth including zero". Python's fnmatch
+        # does NOT treat '**/*.mat' as matching a root-level 'S01.mat' (it
+        # requires at least one directory). LLMs routinely emit '**/' patterns
+        # even for flat datasets, so also try the pattern with a leading '**/'
+        # stripped, making depth-zero match too.
+        if fnmatch.fnmatch(relpath, pat):
+            return True
+        if pat.startswith('**/'):
+            return fnmatch.fnmatch(relpath, pat[3:])
+        return False
+
+    # ── Choose the authoritative SUBJECT source entry ─────────────────
+    # subject correctness has an objective anchor: how many DISTINCT subjects a
+    # rule yields across all files. When --nsubjects is known it is the oracle,
+    # so pick the entry whose distinct-subject count is CLOSEST to nsubjects
+    # (this rejects both collapse, e.g. 40→2, and inflation, e.g. run folded
+    # into subject giving 20→60). Without nsubjects, fall back to the entry
+    # that yields the MOST distinct subjects (best effort). Ties break to the
+    # earliest entry. Every OTHER role still merges first-non-empty below.
+    def _distinct_subjects(entry):
+        seen = set()
+        for relpath in files:
+            if not _match(relpath, entry.get('applies_to', {})):
+                continue
+            r = _resolve_roles_partial(relpath, entry.get('roles', {})).get('subject')
+            if r:
+                seen.add(_san_label(r))
+        return seen
+
+    best_entry, best_key = None, None
+    for entry in naming_structure:
+        if not isinstance(entry, dict):
+            continue
+        n = len(_distinct_subjects(entry))
+        if n == 0:
+            continue
+        # sort key: with nsubjects, minimise |n - nsubjects| then prefer larger n;
+        # without, just maximise n. Smaller key wins.
+        if nsubjects:
+            key = (abs(n - nsubjects), -n)
+        else:
+            key = (-n,)
+        if best_key is None or key < best_key:
+            best_entry, best_key = entry, key
+
+    raw_per_file = {}          # relpath -> raw entities (subject_raw kept)
+    for relpath in files:
+        merged: Dict[str, str] = {}
+        # subject comes ONLY from the authoritative entry
+        if best_entry is not None and _match(relpath, best_entry.get('applies_to', {})):
+            s = _resolve_roles_partial(relpath, best_entry.get('roles', {})).get('subject')
+            if s not in (None, ''):
+                merged['subject'] = s
+        # every OTHER role merges first-non-empty across all matching entries
+        for entry in naming_structure:
+            if not isinstance(entry, dict):
+                continue
+            if not _match(relpath, entry.get('applies_to', {})):
+                continue
+            partial = _resolve_roles_partial(relpath, entry.get('roles', {}))
+            for k, v in partial.items():
+                if k == 'subject':
+                    continue                     # subject already fixed above
+                if v not in (None, '') and not merged.get(k):
+                    merged[k] = v
+        if merged.get('subject'):
+            raw_per_file[relpath] = merged
+
+    # canonical subject key = alphanumeric only, so 'L_06' and 'L06' collapse
+    # to one subject no matter how the LLM joined the source tokens.
+    distinct = sorted({_san_label(e['subject']) for e in raw_per_file.values()},
+                      key=lambda s: (len(re.sub(r'[^0-9]', '', s)), s))
+    subj_strat = 'numeric' if id_strategy in ('auto', 'numeric') else 'semantic'
+    canon_to_id, subject_map = {}, {}
+    for i, c in enumerate(distinct, 1):
+        sid = str(i) if subj_strat == 'numeric' else c
+        canon_to_id[c] = sid
+        subject_map[sid] = c
+
+    per_file = {}
+    for relpath, e in raw_per_file.items():
+        c = _san_label(e['subject'])
+        per_file[relpath] = {
+            'subject':     canon_to_id[c],
+            'subject_raw': c,
+            'ses':  _san_label(e['ses'])  if e.get('ses')  else '',
+            'run':  _san_index(e['run'])  if e.get('run')  else '',
+            'task': _san_label(e['task']) if e.get('task') else '',
+            'acq':  _san_label(e['acq'])  if e.get('acq')  else '',
+        }
+    return per_file, subject_map
+
+
 # ============================================================================
 # Testing
 # ============================================================================
diff --git a/autobidsify/llm.py b/autobidsify/llm.py
index eefb971..9214739 100644
--- a/autobidsify/llm.py
+++ b/autobidsify/llm.py
@@ -790,6 +790,56 @@ def _call_llm(model: str, system_prompt: str, user_payload: str,
 OUTPUT: Raw YAML only (no markdown, no explanation)
 """
 
+PROMPT_NAMING_STRUCTURE = """You label the ROLE of each token POSITION in filenames. \
+You do NOT write regex or code. You only output a YAML naming-structure entry.
+
+You receive, for one group of same-structured files:
+- per-segment token distributions (segment -1 = filename, -2 = its parent dir, etc.)
+- a few sample relative paths, already split into tokens per segment
+- a dataset description
+- id_strategy (numeric = sequential ids; semantic = keep meaningful label)
+
+Output ONE YAML object with keys 'applies_to' and 'roles'. Roles are:
+subject (REQUIRED), session, run, task, acq. Each role has:
+  mode: from_path | constant | lookup | none
+  sources: [{segment: int, position: int}, ...]   # for from_path/lookup key
+  join: ''                                         # optional, joins multi-source
+  value: ...                                       # for constant
+  table: {raw: id}                                 # for lookup only
+For subject also add: id_strategy: numeric|semantic
+For run add: as_index: true   (run MUST be an integer index in BIDS)
+
+Rules:
+- A token that is identical in EVERY file (e.g. the literal word 'session') is NOT
+  a value; use the neighboring numeric position as the index and ignore the literal.
+- If a distinguishing token (e.g. paretic side R/L) is NOT the subject id, do not put
+  it in subject.sources; the subject id is the identifying number/label only.
+- If the subject spans multiple positions (e.g. site + number to avoid cross-site
+  collisions), list all of them in sources in order.
+- SUBJECT UNIQUENESS IS MANDATORY. Subject ids may REPEAT across sibling grouping
+  directories such as group (PD/control), condition, session, or site. Numbers like
+  01..20 under BOTH PD/ and control/ are 40 DIFFERENT people, not 20. When ids can
+  repeat across a grouping level, the subject role MUST include that grouping
+  directory as an ADDITIONAL source together with the number, so every subject stays
+  globally unique (e.g. sources: group-dir + number-dir → PD01, control01).
+- USE nsubjects AS A CHECK. If user_hints.n_subjects is given, the subject sources you
+  choose MUST yield exactly that many DISTINCT subjects across all files. If a single
+  source yields fewer (because ids repeat across groups), you chose too shallow — add
+  the parent grouping directory as another source until the distinct count matches
+  n_subjects. Never pick a subject source that collapses distinct people together.
+- If the id is not derivable from the path at all, use mode: lookup with a table you
+  build from the description; otherwise use from_path.
+Output ONLY the YAML, no prose, no code fences.
+- To select a WHOLE path segment (the common case for subject), give ONLY the
+  segment and OMIT position, e.g. subject.sources: [{segment: -1}] takes the
+  entire filename stem 'S01' as the id. This is ROBUST: you do NOT need to
+  count how a segment splits into letter/digit tokens. PREFER whole-segment for
+  subject. Only add 'position' when the id is truly a fragment inside a segment
+  that also contains unrelated tokens.
+- If a subject spans multiple segments (e.g. group dir + number dir, or
+  site + number), list one whole-segment source per level in order:
+  subject.sources: [{segment: -3}, {segment: -2}]."""
+
 # ── Anonymize instruction snippets (appended to prompts when anonymize=True) ─
 
 _ANON_INSTRUCTION_TRIO = """
@@ -1315,4 +1365,8 @@ def llm_bids_plan(model: str, payload: str,
     if anonymize:
         prompt = prompt + _ANON_INSTRUCTION_PLAN
     return _call_llm(model, prompt, payload,
-                     "BIDSPlan", temperature=0.15)
\ No newline at end of file
+                     "BIDSPlan", temperature=0.15)
+
+def llm_label_naming_structure(model: str, payload: str) -> str:
+    return _call_llm(model, PROMPT_NAMING_STRUCTURE, payload,
+                     "NamingStructure", temperature=0.1)
\ No newline at end of file