Add porting-qmrlab-models skill

[agahkarakuzu]

Adds a repository skill that guides porting qMRI models from qMRLab (MATLAB) into qmrust, and removes the one model-specific special-case from the pure core that motivated it.

The skill — .claude/skills/porting-qmrlab-models/
Phase-gated guidance (read the qMRLab class → translate to a pure Rust fitter → wire in → fetch/bidsify/validate against qMRLab), built around the insight that a port is translating one subclass into another (qMRLab AbstractModel ⇄ the Model/ModelConfig traits).

• SKILL.md — OO correspondence table, six phases with checkpoint gates, definition-of-done tiers; references docs/agents/ADDING-A-MODEL.md rather than restating it.
• scaffold_model.sh (+ self-test) — clones the living inversion_recovery model into a compiling skeleton; deriving from a tested model means it can't drift from the trait.
• references/ — reading qMRLab, MATLAB→Rust translation, optional inputs, validation.

Supporting core change

• Replaced if model == "qmt_spgr" in SimConfig::validate with a polymorphic Model::sim_required_aux() seam; fit path unchanged, round-trip tests hold.

Summary by CodeRabbit

• New Features
  • Simulation now validates that any model-declared “sim-critical” auxiliary inputs (e.g., R1 map when enabled by fitting options) are provided at runtime.
  • BIDS conversion uses per-model volume definitions for output layout, filenames, metadata, and auxiliary-input handling.
• Bug Fixes
  • Improved simulation validation by separating general simulation settings from model-specific input requirements.
• Documentation
  • Added/expanded guides for porting qMRLab models, reading and translating MATLAB logic, correctly handling optional inputs, validating ports end-to-end, and updating the model-adding checklist and BIDSify behavior.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 9d6e36c7-e5d2-4699-b790-925b8be0436d

📥 Commits

Reviewing files that changed from the base of the PR and between c2cf802 and a3627f1.

📒 Files selected for processing (4)

• .claude/skills/porting-qmrlab-models/SKILL.md
• .claude/skills/porting-qmrlab-models/references/optional-inputs.md
• .claude/skills/porting-qmrlab-models/references/reading-qmrlab.md
• .claude/skills/porting-qmrlab-models/references/translation-patterns.md

🚧 Files skipped from review as they are similar to previous changes (3)

• .claude/skills/porting-qmrlab-models/references/translation-patterns.md
• .claude/skills/porting-qmrlab-models/references/reading-qmrlab.md
• .claude/skills/porting-qmrlab-models/references/optional-inputs.md

---

📝 Walkthrough

Walkthrough

The pull request documents a phased qMRLab model-porting workflow, adds model scaffolding and self-testing scripts, introduces simulation-specific auxiliary-input validation, and updates Model/BIDS integration guidance.

Changes

Porting workflow and simulation contracts

Layer / File(s)	Summary
Porting workflow and validation guidance .claude/skills/porting-qmrlab-models/*	Adds qMRLab mapping, translation, optional-input, validation, and completion-gate guidance.
Model scaffold generation and self-test .claude/skills/porting-qmrlab-models/*.sh	Adds automated model cloning, registry/module/grouping wiring, TODO markers, structural checks, cleanup, and compilation tests.
Simulation auxiliary-input contract crates/qmrust-core/src/{config.rs,core/model.rs,models/qmt_spgr/adapter.rs,sim/*}	Separates intrinsic simulation validation from model-declared auxiliary requirements and conditionally validates qMT-SPGR R1map.
Model and BIDS integration documentation docs/agents/*.md	Documents volume-oriented Model methods, required BIDS grouping entries, and registry-driven bidsify behavior.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Possibly related PRs

• qMRLab/qmrust#5: Extends the shared Model and QmtModel interfaces touched by this pull request.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: adding the porting-qmrlab-models skill.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/model-port-skill

---

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 5

🧹 Nitpick comments (1)

crates/qmrust-core/src/sim/model.rs (1)

95-107: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Test both branches of the R1map requirement.

Add an explicit use_r1map_to_constrain_r1f: true case and a false case that accepts a missing sim.r1; the current test relies on the default and only protects the enabled branch.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@crates/qmrust-core/src/sim/model.rs` around lines 95 - 107, The test
sim_enforces_model_declared_aux currently covers only the default enabled R1map
requirement. Extend it with explicit use_r1map_to_constrain_r1f: true and false
configurations, asserting the true case rejects missing sim.r1 and accepts it
when supplied, while the false case accepts a missing sim.r1.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In @.claude/skills/porting-qmrlab-models/references/validation.md:
- Around line 69-71: The Tier 3 validation definition must require a direct
numerical comparison against qMRLab FitResults, not only OSF fitting and
BIDS-vs-.mat round-trip parity. Update the Tier 3 guidance around the OSF and
qMRust-cli validation references to specify the comparison and an explicit
tolerance; otherwise reclassify those checks as Tier 2 or prerequisites.

In @.claude/skills/porting-qmrlab-models/scaffold_model.sh:
- Around line 45-56: Update scaffold_model.sh to validate that NAME/SUFFIX are
absent from both the registry and grouping file before the perl insertion or
grouping append occurs. If either identity already exists, print an error and
exit nonzero before mutating either file; preserve the existing creation flow
for new entries.

In @.claude/skills/porting-qmrlab-models/SKILL.md:
- Around line 44-46: Update the scaffold command in
`.claude/skills/porting-qmrlab-models/SKILL.md` lines 44-46 and
`.claude/skills/porting-qmrlab-models/references/translation-patterns.md` lines
11-13 to use the repository-relative script path
`.claude/skills/porting-qmrlab-models/scaffold_model.sh`, so both instructions
work when run from the repository root.

In @.claude/skills/porting-qmrlab-models/test_scaffold.sh:
- Around line 7-18: Update the test scaffold setup and cleanup around NAME,
cleanup(), and the EXIT trap to preserve the worktree: refuse to run when the
scaffold_probe directory already exists, and snapshot the affected registry,
module-list, and grouping files before changes, restoring those snapshots during
cleanup instead of using git checkout. Ensure cleanup does not remove any
pre-existing probe directory.

In `@crates/qmrust-core/src/sim/model.rs`:
- Around line 15-29: Make validate_sim_inputs and sim_aux support all logical
names accepted by Model::sim_required_aux, ensuring model-declared auxiliary
inputs can be supplied through SimConfig. If the simulation configuration cannot
represent arbitrary names, replace the generic contract with explicit validation
that rejects unsupported names rather than reporting them as missing.

---

Nitpick comments:
In `@crates/qmrust-core/src/sim/model.rs`:
- Around line 95-107: The test sim_enforces_model_declared_aux currently covers
only the default enabled R1map requirement. Extend it with explicit
use_r1map_to_constrain_r1f: true and false configurations, asserting the true
case rejects missing sim.r1 and accepts it when supplied, while the false case
accepts a missing sim.r1.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 8b27be85-c39b-4549-ae56-ef715a336b78

📥 Commits

Reviewing files that changed from the base of the PR and between 43b7e45 and 9fb8519.

📒 Files selected for processing (15)

• .claude/skills/porting-qmrlab-models/SKILL.md
• .claude/skills/porting-qmrlab-models/references/optional-inputs.md
• .claude/skills/porting-qmrlab-models/references/reading-qmrlab.md
• .claude/skills/porting-qmrlab-models/references/translation-patterns.md
• .claude/skills/porting-qmrlab-models/references/validation.md
• .claude/skills/porting-qmrlab-models/scaffold_model.sh
• .claude/skills/porting-qmrlab-models/test_scaffold.sh
• crates/qmrust-core/src/config.rs
• crates/qmrust-core/src/core/model.rs
• crates/qmrust-core/src/models/qmt_spgr/adapter.rs
• crates/qmrust-core/src/sim/mod.rs
• crates/qmrust-core/src/sim/model.rs
• docs/agents/ADDING-A-MODEL.md
• docs/agents/ARCHITECTURE.md
• docs/agents/DATA-PIPELINE.md