nomologR Roadmap

Mission: Make rigorous construct validation easier to learn, easier to execute, and easier to defend.

nomologR is a guided, evidence-based workflow for empirical scale development and construct validation. It coordinates established R engines (primarily psych, EFAtools, lavaan, and semTools) while adding transparent diagnostics, literature-linked explanations, decision logging, and theory-aware guidance.

Audience: graduate students (master’s and doctoral) learning these techniques, the faculty who teach and advise them, and researchers who apply them.

Core principle: Flag, explain, and document. Never silently delete.

Current stable release: 0.3.0 (September 26, 2026), GPL-3.0-only — the first release submitted to CRAN. It adds the contentvalidR handoff reader, carries the v0.2.1 tools into the guided workflow and its report, and adds a written stability policy. It follows 0.2.1 (September 23, 2026) and 0.2.0 (September 19, 2026). The earlier 0.1.0 release (September 9, 2026) keeps its original MIT license. Next release: v1.0.0 — the joint release with contentvalidR (#53), scoped in #113. See v1.0.0 below; candidates for 1.x follow it. Distribution: R-universe, which builds each GitHub release. v0.3.0 is submitted to CRAN (#39).

The complete v0.1 milestone specifications, exit gates, and certification records are preserved verbatim in dev/roadmap-v0.1-record.md. Those records are historical; they are not new verification results.

---

1. Package Boundary

The JUhalt measurement/design ecosystem should remain intentionally modular:

• contentvalidR — conceptual/content evidence before or during item development: construct definition, item generation, substantive/content validity, expert/sorter judgments.
• nomologR — empirical measurement and construct-validity evidence: item/data audit, dimensionality, EFA, CFA, reliability, convergent/discriminant evidence, measurement invariance, and theory-specified nomological networks.
• solomonR — Solomon four-group experimental design analysis: pretest sensitization, treatment effects, combination procedures, robust alternatives.

Natural handoff

contentvalidR → nomologR → substantive/experimental research
solomonR is invoked only when the substantive study uses a Solomon four-group design.

Partners, and a separate project

nomologR and contentvalidR are partners: one workflow from content review to empirical validation, joined by the handoff (#46). They are kept on the same page about the handoff before and after 1.0, release 1.0.0 together (#53), and move major versions together whenever the shared contract changes. solomonR is a separate project: it takes no part in the handoff or the joint release, and neither package depends on it. *** ## 2. Design Principles

Every public function and report should follow these principles.

1. Measurement before structure.
2. Evidence accumulates; validity is not a single test.
3. Cutoffs are reference points, not universal laws.
4. No automatic item deletion.
5. Estimator/correlation choices must respect item type.
6. Modification indices never authorize changes by themselves.
7. Nomological evidence must begin with explicit theoretical expectations.
8. A null prediction is not supported merely because p > .05.
9. Every recommendation should state why it was made.
10. Every consequential user decision should be recordable in a decision log.
11. The teaching layer should be separable from the statistical engine.
12. Reproducibility is a release requirement, not an optional feature.
13. Methods are research-backed and situated from historical to contemporary practice. Historical techniques may appear as labeled context; they are never silently substituted for contemporary evidence.
14. Teaching surfaces run on data with a known answer. Examples and vignettes use the simulated teaching datasets so learners can compare evidence with the truth.

See VISION.md for the audience, recommendation standard, and standard for methods.

---

v0.1.0 — Minimum Useful Construct-Validation Workflow

Status: Complete — released September 9, 2026 (release record; closeout issues #12–#16; release PR #18; closeout PR #21).

Milestone	Scope	Functions
M0	Foundation reset	—
M1	Data and item audit	nomo_screen(), nomo_defaults()
M2	Factor-retention evidence	nomo_factors()
M3	Exploratory factor analysis (Checkpoint A)	nomo_efa()
M4	Confirmatory factor analysis	nomo_model(), nomo_split(), nomo_cfa()
M5	Reliability and convergent/discriminant evidence (Checkpoint B)	nomo_reliability(), nomo_validity()
M6	Theory-specified nomological network	nomo_hypotheses(), nomo_network()
M7	Measurement invariance (Checkpoint C)	nomo_invariance(), nomo_partial(), nomo_table()
M8	One-stop guided pipeline	nomo_run()
M9	Reproducible report	nomo_report()

Detailed scope, tests, coverage closeouts, and exit gates for each milestone are in dev/roadmap-v0.1-record.md.

---

# v0.2.0 — Research-Backed, Usable Measurement Workflows

Status: Released September 19, 2026. Scope selected in #22. Every Core workstream shipped; six Planned workstreams moved to v0.2.1 at certification, each with its reason recorded on the issue.

Goals. Make nomologR:

1. useful to graduate students and researchers applying scale-development and construct-validation techniques;
2. backed by research, covering techniques from historical to contemporary practice with verifiable references; and
3. usable and informative, with runnable examples, walkthroughs on data with known answers, and output that explains its reasoning.

Core workstreams must ship in v0.2.0. Planned workstreams are in scope but may move to a later release with a recorded rationale. Each issue records the user problem, historical-to-contemporary lineage, estimand, assumptions and unsupported cases, validation plan, and exit criteria.

Core workstreams

• #25 Learning foundations — teaching datasets, runnable vignettes and examples, site navigation (completed in #41).
• #26 Research basis — historical-to-contemporary methods documentation, verified references, methods registry. References and the research-basis article shipped in #41; nomo_methods(), report-level citations of the methods a run used, and release-time DOI verification completed the workstream.
• #27 Model comparison — nomo_compare() for nested and non-nested measurement models.
• #28 Revision lineage — auditable revise-and-compare cycles in nomo_run().
• #29 Bifactor and higher-order measurement models — nomo_model() structures and nomo_hierarchical() indices.
• #30 Replication-status language for near-zero sign changes — a sign change is a reversal only when both confidence intervals exclude zero on opposite sides.
• #37 Release certification, CRAN-readiness gate, and R-universe publication.

Planned workstreams

• #31 Human-readable invariance local-strain labels (completed in #41).
• #32 Missing-data sensitivity across measurement stages. Moved to v0.2.1; shipped there.
• #33 Score guidance — nomo_scores() for sum and factor scores. Moved to v0.2.1; shipped there.
• #34 Insufficient-effort responding screen in nomo_screen(). Moved to v0.2.1; shipped there.
• #35 Manuscript-ready tables and Word report output. Moved to v0.2.1; shipped there.
• #36 Maintenance — test organization, nomo_run.R modularization, minimum-dependency CI.
• #40 nomo_report() rendering from inside R Markdown or Quarto documents. Moved to v0.2.1; shipped there.
• #42 Optional parallel bootstrap for reliability confidence intervals. Moved to v0.2.1; shipped there.

Suggested sequence

1. Foundations (done): #25 and #31, with #26 maintained alongside every later workstream.
2. Safe structure for revision work: #36 (done), then #27 (done), then #28 (done).
3. Broader measurement models and interpretation: #29 (builds on #27) and #30.
4. Usability extensions: #32, #33, #34, #35, #40, #42 — moved to v0.2.1 at certification and shipped in 0.2.1.
5. Release: #37, including the license/version/date gate carried from #22 and the CRAN-readiness gate.

Deferred from v0.2 scope selection

Tracked for v0.3 scope selection in #38, each with a rationale: ESEM; longitudinal invariance; multiple-imputation integration; bootstrap stability summaries; CFA/SEM sample-size and power planning; criterion/predictive evidence beyond network outcomes; and research proposal #23 (model-specific fit diagnostics). None were rejected.

---

v0.2.1 — Completing the v0.2 Workflow

Status: Released September 23, 2026 (v0.2.1 milestone). The six Planned workstreams moved at v0.2.0 certification all shipped, with three workstreams opened during the cycle. Certification is recorded in #70.

• #40 nomo_report() renders from inside R Markdown and Quarto documents.
• #54 Full test coverage of the nomo_compare() failure guards.
• #56 Factor determinacy and construct replicability in nomo_hierarchical(), reproducing Rodriguez, Reise, and Haviland (2016).
• #33 nomo_scores(): scores with Grice’s criteria and the parallel model that unit weighting assumes.
• #34 Careless-responding indices in nomo_screen(), reproducing Curran (2016).
• #62 Disclosure of relationships estimated between observed variables, naming lavaan::sam() and Skrondal and Laake’s (2001) scoring design.
• #42 Optional parallel bootstrap for reliability intervals.
• #35 nomo_apa_table() and Word output from nomo_report().
• #32 nomo_missing(): listwise deletion against FIML, or pairwise deletion for ordered indicators.
• #70 Release certification and R-universe publication.

---

v0.3.0 — First CRAN Release

Status: Released September 26, 2026 (v0.3.0 milestone), with scope selected on September 23, 2026, in #38. The scope is deliberately lean: v0.3.0 carries the first CRAN submission, so it selects only what makes that submission complete, stable, and well tested. Certification is recorded in #75, and the CRAN outcome will be recorded in #39.

• #39 First CRAN submission; see Distribution below. Spelling, URLs, build exclusions, and test time under CRAN conditions are done.
• #46 A contentvalidR handoff reader. It is tested against stored producer fixtures from contentvalidR 0.6.0 and 0.7.0, and neither package depends on the other.
• #72 Restore full test coverage after v0.2.1. Reviewing each uncovered line found four defects, now fixed.
• #73 The guided workflow and report carry scores, careless-responding screens, missing-data sensitivity, and APA tables.
• #74 A written API-stability and deprecation policy, which the joint 1.0 release requires (#53).
• #75 Release certification and CRAN submission.

v0.9.0 — Before 1.0: Presentation, the Historical Record, and Teaching

Status: Released 2026-09-28, with the maintainer’s approval. It carries the 1.0 scope selected in #113 up to that date.

• #89 Console output, plots, and report tables redesigned.
• #113 The historical record in nomo_methods() and the research-basis timeline (#116, #119); within-scale item review (#123, #127); APA tables for validity evidence (#124).
• #60 “From content review to empirical screening” and nomo_demo_walkthrough (#112); “Teaching with nomologR” (#118).
• #114 Returned fields named in every help page (#115); nomo_missing(fit) (#122).

v1.0.0 — Joint Stable Release with contentvalidR

Status: Release candidate planned for 2026-10-17, the same day as contentvalidR’s (decided by the maintainer on 2026-09-28). The scope is set in #113, where the maintainer delegated decisions to what the literature says. On 2026-09-28 the maintainer asked that the gaps social-science scale developers meet be closed before the candidate, starting with reliability-corrected single indicators. The release sequence is in #53.

1.0.0 is the stability promise in ?nomologR. After it, changes to existing behavior need a deprecation cycle, and additions stay free. So anything that would change existing behavior is decided before the freeze. Anything additive can wait for 1.x.

• #60 The companion article “From content review to empirical screening”, on the shared walkthrough data.
• #89 The presentation pass for console output, plots, and reports. The output gallery reports no faults across 35 console outputs and 33 plots.
• #114 An API audit before the freeze: returned fields named in every help page (#115), and nomo_missing() takes fit like the other post-fit functions (#122).
• #113 The historical record: when each method was introduced, and what replaced each historical one, drawn into a timeline in the research-basis article (#116, #119).
• #113 Decisions before the freeze, made on the literature:
  • Both returned flag vocabularies are kept; the display wording is already unified.
  • With two or more declared scales, the item audit reads each item’s item-rest correlation within its own scale (#123).
  • Declared keying stays as coded.
  • nomo_missing()’s flag rule and nomo_apa_table()’s layouts become stable at the release candidate.
• #113 APA tables for convergent and discriminant evidence (#124).
• #39 The CRAN outcome for 0.3.0, which is in CRAN’s queue for new submissions. contentvalidR 0.4.0 was accepted on 2026-09-28, which starts its update interval.
• #53 Release candidates, fixtures from contentvalidR’s RC, the compatibility table, and a same-day release with release notes linking each other. Both packages number a candidate the same way (decided 2026-09-28): DESCRIPTION 0.99.0 and a git tag v1.0.0-rc.N, as a tag only, with no GitHub release, so R-universe does not publish it. CRAN asks for updates no more often than every one to two months, so the joint submission follows the later of the two packages’ first acceptances by that interval.

1.x — Modern Extensions

Status: Candidates for releases after 1.0.0, all additive. They were deferred from v0.3.0 (#38) and again from 1.0.0 (#113). None was rejected. Candidates are not commitments until selected.

• ESEM. lavaan already fits it, so it needs no new dependency, which makes it a natural first candidate.
• Longitudinal invariance.
• Multiple-imputation integration. nomo_missing() covers listwise, FIML, and pairwise sensitivity meanwhile.
• Bootstrap stability summaries.
• CFA/SEM sample-size and power planning.
• Criterion/predictive evidence beyond network outcomes.
• IRT as a complementary item-level framework, and DIF.
• Bayesian CFA/SEM (blavaan) robustness module, posterior predictive checking, and frequentist/Bayesian concordance summaries; with it, content-validity evidence as informative priors (#49).
• Additional equivalence/SESOI functionality beyond v0.1’s researcher-specified negligible regions. No SESOI is invented by the package.
• Model-specific fit diagnostics (#23).

---

Distribution — R-universe, and CRAN from v0.3.0

• Stable releases are published as GitHub releases. R-universe builds each release, usually within a few hours.
• v0.2.0 certification (#37) includes a CRAN-readiness gate: R CMD check --as-cran clean on win-builder, the macOS builder, and R-hub; long-running tests skipped on CRAN; fast examples and vignettes.
• First CRAN submission with v0.3.0 (#39). Decision recorded September 15, 2026: submitting after the v0.2 functions have been used on R-universe avoids repeated CRAN resubmissions while the API is still growing.

---

Long-Term Research Program

Potential research contributions arising from nomologR itself:

1. Decision stability
   • How often do common scale-development heuristics lead researchers to different item sets?
2. Cutoff sensitivity
   • How sensitive are substantive conclusions to common loading, AVE, HTMT, and fit-index cutoffs?
   • Provisional proposal #23: evaluate model-specific CFA fit diagnostics with reproducible simulation provenance, drawing on McNeish and Wolf (2023), doi:10.1037/met0000425. This extends the teaching layer; it is not an automatic validity verdict or a committed release feature.
3. Nomological concordance
   • Develop formal summaries of how well an empirical structural network matches an a priori theoretical network.
4. Researcher degrees of freedom
   • Quantify the decision tree generated by item removal, residual correlations, estimator choices, and model respecification.
5. Bayesian nomological evidence
   • Posterior probability that predicted path direction/magnitude satisfies a prespecified theoretical region.
6. Teaching outcomes
   • Test whether guided nomologR reports improve methodological understanding relative to conventional software output.

---

Development Workflow / Checkpoint Discipline

For every workstream:

1. Open an issue defining scope, historical-to-contemporary lineage, and exit criteria.

2. Implement on a feature branch.

3. Add tests before or alongside substantive code, including known-answer checks on teaching or simulated data.

4. Add DOI-verified references and update the reference documentation, relevant vignette, and research basis article.

5. Run:

   devtools::document()
   devtools::test()
   devtools::check()

6. Push and require GitHub Actions to pass.

7. Review API/output for teaching clarity.

8. Merge only after exit criteria are satisfied.

9. Update NEWS.md and check off roadmap items.

10. Tag a release candidate when appropriate.

Rule for scope creep

A feature may enter the current release only if it is necessary for: - statistical correctness, - reproducibility, - documentation, - or the release’s stated goals.

Otherwise it goes into the next-version candidate list.

---

Definition of Success

nomologR succeeds if a graduate student or applied researcher can start with a candidate measure and finish with:

• a defensible measurement model,
• transparent evidence about reliability and construct validity,
• a theory-specified nomological network,
• a record of every important analytic decision,
• reproducible R code,
• an understanding of where each method came from and what current research recommends,
• and an explanation of why each step was taken.

The package should make the process cleaner without making it more automatic than the science allows.